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iV iSeries: Cryptographic hardware 


Part 1. Cryptographic hardware 


IBM® offers two cryptographic hardware solutions for customers that require a high level of security for 
data stored on their iSeries™ server, and for SSL transactions. These options have a lot to offer iSeries 
server customers, including enhanced SSL performance. IBM offers the following cryptographic hardware 
options: 

¢ IBM 2058 e-Business Cryptographic Accelerator (Hardware Feature code 4805) 

¢ IBM 4758 Cryptographic Coprocessor (Hardware Feature codes 4801 or 4802) 


The benefits of each cryptographic hardware option include: 
¢ IBM 2058 e-Business Cryptographic Accelerator (Hardware Feature code 4805) 
— Offers a large capacity for accelerating SSL transactions 
— Minimal installation and configuration effort 
— Minimal management requirements 
¢ IBM 4758 e-Business Cryptographic Coprocessor (Hardware Feature codes 4801, and 4802) 
— Minimal installation effort 
— Tamper-resistant hardware features 
— Numerous configuration options, enabling you to customize its functions to fit your needs 
— Provides secure key storage for applications and SSL transactions 


— Offers a rich set of cryptographic functions for applications, including Triple-DES, RSA digital 
signature support, financial PIN processing, and robust key management services 


By installing cryptographic hardware in your iSeries server, you can make cryptography an integral part of 
your security solution. To ensure that you understand how cryptographic hardware works and how you can 
implement it in your system, review the following pages: 


* |What’s new for V5R2|makes available to you the new features or functions available for this release of 


the iSeries server. 


* {Print this topic] explains the printing options available to you for this topic. 


¢ Usage scenarios offer some example configurations or uses of cryptographic hardware with iSeries 
servers: 


Cryptographic hardware scenario: Enhance iSeries SSL performance 


Cryptographic hardware scenario: Protect private keys with cryptographic hardware 


— {Cryptographic hardware scenario: Write an OS/400® application to use the 4758 Cryptographic 


¢ |Cryptography concepts}explain some basic cryptographic concepts, enabling you to better understand 


cryptographic hardware and how to maximize your usage of it with your iSeries server. 
* Choosing the best cryptographic hardware for your iSeries server: 


— |2058 Cryptographic Accelerator for iSeries|includes planning and configuration information for the 


2058 Cryptographic Accelerator. 


— |4758 Cryptographic Coprocessor for iSeries|includes planning and configuration information for the 


4758 Cryptographic Coprocessor. 


Note: This information includes programming examples. Read the|Chapter 7, “Code disclaimer 
information” on page 283]for important legal information. 


¢ |Related information| points to other sources of cryptographic information, as well as related product 


information sites. 
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2 iSeries: Cryptographic hardware 


Chapter 1. What’s new for V5R2 


If you are looking for the latest information regarding new cryptographic hardware, and added features to 
existing cryptographic hardware options for iSeries servers, you have come to the right place. 


2 
New cryptographic hardware: IBM 2058 e-Business Cryptographic Accelerator 


The IBM 2058 e-Business Cryptographic Accelerator (Hardware Feature code 4805, and hereafter referred 
to as the 2058 Cryptographic Accelerator) is available, in addition to the 4758 Cryptographic Coprocessor. 
Designed to improve iSeries performance by rerouting the processing of private keys away from the 
system processors, this hardware option is an excellent choice for iSeries implementations that handle 
high volumes of SSL (Secure Sockets Layer) transactions. While the 2058 Cryptographic Accelerator is an 
excellent choice for enhancing the SSL performance of iSeries servers, and is easy to install and intialize, 
it does not offer the wide range of configuration options that the 4758 Coprocessor offers. 


See |2058 Cryptographic Accelerator for iSeries} for more information that can help you decide which 


cryptographic hardware option works best for your iSeries server implementation. 
Additional function: 4758 Cryptographic Coprocessor 


The 4758 Cryptographic Coprocessor offers customers the following new capabilities: 
¢ Financial pin processing: Unique key per transaction (UKPT) 
* Common Cryptographic Architecture (CCA) 2.4 


New cryptographic hardware scenarios 


To give you some ideas on how you can use cryptographic hardware with your iSeries server, we have 
added the following scenarios to the iSeries Information Center: 


¢ |Cryptographic hardware scenario: Enhance iSeries SSL performance 


¢ |Cryptographic hardware scenario: Protect private keys with cryptographic hardware 


¢ |Cryptographic hardware scenario: Write an OS/400 application to use the 4758 Cryptographic 


To find other information about what's new or changed this release, see the 


& 
How to see what’s new or changed 


To help you see where technical changes have been made, this information uses: 
°* The 


a 
image to mark where new or changed information begins. 
* The *€ image to mark where new or changed information ends. 
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4 iSeries: Cryptographic hardware 


Chapter 2. Print this topic 


You can view or download the PDF version of these topics: 


¢ |Cryptographic hardware] (about 756 KB or 292 pages) contains all of the information regarding IBM 


cryptographic hardware supported for the iSeries server at V5R2. 


¢ 12058 Cryptographic Accelerator (about 79 KB or 24 pages) contains information regarding the 2058 


Cryptographic Accelerator hardware supported for the iSeries server at V5R2. 


¢ 14758 Cryptographic Coprocessor} (about 753 KB or 296 pages) contains information regarding the 4758 


Cryptographic Coprocessor hardware supported for the iSeries server at V5R2. 
Saving PDF files 
To save a PDF on your workstation for viewing or printing: 
1. Right-click the PDF in your browser. 
2. Click Save Target As. 
3. Navigate to the directory in which you would like to save the PDF. 
4. Click Save. 
Downloading Adobe Acrobat Reader 


If you need Adobe Acrobat Reader to view or print these PDFs, you can download a copy from the 
(www.adobe.com/products/acrobat/readstep.html) . 
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6 iSeries: Cryptographic hardware 


Chapter 3. Concepts 


Cryptography 


Cryptography is the art and science of keeping data secure. Basic cryptography services ensure that 
messages are private, that the integrity of a message is maintained, that the communicating parties are 
authenticated and that a party involved in a communication cannot refute having sent a message 


Cryptography allows you to store information or to communicate with other parties while preventing 
non-involved parties from understanding the stored information or understanding the communication. 
Encryption transforms understandable text into an unintelligible piece of data (ciphertext). Decrypting 
restores the understandable text from the unintelligible data. Both processes involve a mathematical 
formula or algorithm and secret data (the key). 


Cryptographic algorithms 


There are two types of cryptographic algorithms: 


1. With a secret or symmetric key algorithm, one key is a shared secret between two communicating 
parties. Encryption and decryption both use the same key. The Data Encryption Standard (DES) and 
Triple DES are examples of secret key algorithms. 


2. With a public key or asymmetric key algorithm, a pair of keys is used. One of keys, the private key, 
is kept secret and not shared with anyone. The other key, the public key, is not secret and is shared 
with anyone. When data is encrypted by one of the keys, it can only be decrypted and recovered by 
using the other key. The two keys are mathematically related, but it is virtually impossible to derive the 
private key from the public key. The RSA algorithm is an example of a public key algorithm. 


Both types of algorithms use keys to determine how to change the data. Different cryptographic processes 
use an algorithm to achieve one of several purposes. You choose the cryptographic process to use 
depending on the purpose, for example generating a message authentication code (MAC) to ensure data 
integrity. A user-written application for the 4758 Cryptographic Coprocessor calls the cryptographic process 
by using the corresponding security application programming interface (SAPI). Together the key and 
cryptographic process transform the data. A user with authorization to the SAPI has access to that 
cryptographic process. Therefore, the key controls access to the data. You must safeguard the keys to 
protect the data. If you keep the key value secret, you ensure the security of your data with each use of 
the algorithm with the key. 


Encryption 


With field level encryption, the user application explicitly requests cryptographic services. The user 
application completely controls key generation, selection, and distribution. The user application also 
controls what data to encrypt and what data to keep as plain-text. With encryption at the session layer, the 
system is requesting cryptographic services instead of your application. Your application may or may not 
be aware that encryption is happening. Link level encryption is performed at the lowest level of the 
protocol stack and usually by specialized hardware for that purpose. The 4758 Coprocessor supports both 
field level encryption and Secure Sockets Layer (SSL) session establishment encryption, but not VPN or 
SNA session level encryption. The 2058 Cryptographic Acelerator only supports SSL session 
establishment encryption. 


Data integrity 
To rely on data, you need to know that it comes from an authorized source and is unchanged. This is 
known as data authenticity and data integrity. Your 4758 Coprocessor can ensure authenticity and integrity 


by creating a Message Authentication Code (MAC), a message digest, or a digital signature. 


Message Authentication Code (MAC) 
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The MAC process is a data integrity technique in which you define critical data elements. For example, 
you could define the amount in a funds transfer message. The critical data elements, cryptographic 
algorithm, and secret MAC key generate the MAC. The MAC becomes part of the message and travels 
with it. The MAC process uses DES or Triple DES keys. 


The receiver of the message uses the same MAC key, algorithm, and procedure as the sender to 
reproduce the MAC. If the receiver's MAC matches the MAC sent with the message, they can accept the 
MAC as unaltered. 


The MAC process helps authenticate received messages, but does not prevent unauthorized reading 
because the transmitted data remains as plaintext. By using the MAC process and then encrypting the 
entire message, you can more effectively protect both data privacy and integrity. 


Message digest 


A message digest process can be performed on data to produce a digest value which can be thought of 
as a cryptographically generated checksum. If any portion of the data is modified, a different digest would 
be generated. You can keep copies of message digests, and compare them. Message digests that are 
identical indicate that no data has been modified. 


Digital signature 


A digital signature can also be used to verify authenticity and integrity. It is a two step process: 


1. First a digest is generated from the data and then the digest is encrypted using a private RSA key. The 
result is a digital signature. The signature can be verified by decrypting the signature using the public 
key to recover the original digest. 


2. Another digest is generated from the data and is compared to the original digest. If the two are 
identical, then the signature is validated and you can be confident that the data has not been altered. 


Key types associated with the 4758 Cryptographic Coprocessor 
Your 4758 Coprocessor uses various key types. Not all DES or Triple DES keys can be used for 
all symmetric key operations. Likewise, not all public key algorithm (PKA) keys can be used for all 
asymmetric key operations. This is a list of the various key types which the 4758 Coprocessor 
uses: 


Master key 
This is a clear key, which means that no other key encrypted it. The 4758 Coprocessor 
uses the master key to encrypt all operational keys. The 4758 Coprocessor stores the 
master key in a tamper-responding module. You cannot retrieve the master key from the 
4758 Coprocessor. The 4758 Coprocessor responds to tamper attempts by destroying the 
master key and destroying its factory certification. The 4758-023 has two master keys: 
one for encrypting DES keys and one for encrypting PKA keys. 


Double-length key-encrypting keys 
Your 4758 Coprocessor uses this type of Triple-DES key to encrypt or decrypt other DES 
or Triple DES keys. Key-encrypting-keys are generally used to transport keys between 
systems. However, they can also be used for storing keys offline for backup. If 
key-encrypting-keys are used to transport keys, the clear value of the key-encrypting-key 
itself must be shared between the two systems. Exporter key-encrypting keys are used for 
export operations where a key encrypted under the master key is decrypted and then 
encrypted under the key-encrypting key. Importer key-encrypting keys are used for import 
operations where a key encrypted under the key-encrypting key is decrypted and then 
encrypted under the master key. 


Double-length PIN keys 
Your 4758 Coprocessor uses this type of key to generate, verify, encrypt, and decrypt 
PINs used in financial operations. These are Triple DES keys. 
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MAC keys 
Your 4758 Coprocessor uses this type of key to generate Message Authentication Codes 
(MAC). These can be either DES or Triple DES keys. 


Cipher keys 
Your 4758 Coprocessor uses this type of key to encrypt or decrypt data. These can be 
either DES or Triple DES keys. 


Single-length compatibility keys 
Your 4758 Coprocessor uses this type of key to encrypt or decrypt data and generate 
MACs. These are DES keys and are often used when encrypted data or MACs are 
exchanged with systems that do not implement the Common Cryptographic Architecture. 


Private keys 
Your 4758 Coprocessor uses private keys for generating digital signatures and for 
decrypting DES or Triple DES keys encrypted by the public key. 


Public keys 
Your 4758 Coprocessor uses public keys for verifying digital signatures, for encrypting 
DES or Triple DES keys, and for decrypting data encrypted by the private key. 


Key forms 
The 4758 Coprocessor works with keys in one of four different forms. The key form, along with the 
key type, determines how a cryptographic process uses that key. The four forms are: 


Clear form 
The clear value of the key is not protected by any cryptographic means. Clear keys are 
not usable by the 4758 Coprocessor. The clear keys must first be imported into the secure 
module and encrypted under the master key and then stored outside the secure module. 


Operational form 
Keys encrypted under the master key are in operational form. They are directly usable for 
cryptographic operations by the 4758 Coprocessor. Operational keys are also called 
internal keys. All keys that are stored in the server key store file are operational keys. 
However, you do not need to store all operational keys in the key store file. 


Export form 
Keys encrypted under an exporter key-encrypting key as the result of an export operation 
are in export form. These keys are also called external keys. A key in export form can also 
be described as being in import form if an importer key-encrypting key with the same clear 
key value as the exporter key-encrypting key is present. You may store keys in export 
form in any manner that you choose, however, you can not store them in key store files. 


Import form 
Keys encrypted under an importer key-encrypting key are in import form. Only keys in 
import form can be used as the source for an import operation. These keys are also called 
external keys. A key in import form can also be described as being in export form if an 
exporter key-encrypting key with the same clear key value as the importer key-encrypting 
key is present. You may store keys in import form in any manner that you choose, 
however, you can not store them in key store files. 


Function control vector 
IBM provides a digitally signed value known as a function control vector. This value enables the 
cryptographic application within the 4758 Coprocessor to yield a level of cryptographic service 
consistent with applicable import regulations and export regulations. The function control vector is 
shipped with the IBM Cryptographic Access Provider (5722—ACx) product you install on your 
system. The path name of the file is /QIBM/ProdData/CAP/FCV.CRT. The function control vector 
provides your 4758 Coprocessor with the key length information necessary to create keys. 
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Control vectors 
A control vector, different from a function control vector, is a known value associated with a key 
that governs the following: 


* Key type 

¢ What other keys this key can encrypt 

¢ Whether your 4758 Coprocessor can export this key 
¢ Other allowed uses for this key 


The control vector is cryptographically linked to a key and can not be changed without changing 
the value of the key at the same time. 


Key store file 
An OS/400 database file that is used to store keys which you encrypted under the master key of 
the 4758 Coprocessor. 


Key token 
A data structure that can contain a cryptographic key, a control vector, and other information 
related to the key. Key tokens are used as parameters on most of the CCA API verbs that either 
act on or use keys. 
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Chapter 4. 2058 Cryptographic Accelerator for iSeries 


a 


The 2058 Cryptographic Accelerator is available for customers to use with a V5R2 (or later) iSeries server. 
The 2058 Cryptographic Accelerator provides a competitive option to customers who do not require the 
high security of a 4758 Cryptographic Coprocessor, but do need the high cryptographic performance that 
hardware acceleration provides to offload a host processor. The 2058 Cryptographic Accelerator has been 
designed to improve the performance of those SSL applications that do not require secure key storage. It 
does not provide tamper-resistant storage for keys, like the 4758 Cryptographic Coprocessor. You can 
install up to four 2058 Cryptographic Accelerator cards in an iSeries server. 


The 2058 Cryptographic Accelerator provides special hardware which is optimized for RSA encryption 
(modular exponentiation) with data key lengths up to 2048 bits. The 2058 Accelerator uses multiple RSA 


(Rivest, Shamir and Adleman algorithm) engines. Refer to the|iSeries Performance Management ad web 


site for performance information specific to your iSeries server model. 


For more information about the 2058 Cryptographic Accelerator, refer to the following pages: 


* 12058 Cryptographic Accelerator features 

¢ |Cryptographic hardware scenario: Enhance iSeries SSL performance 
Plan for the 2058 Cryptographic Accelerator 

Configure the 2058 Cryptographic Accelerator 

2058 Cryptographic Accelerator features 


Some features of the 2058 Cryptographic Accelerator include: 

¢ Single card high performance cryptographic adapter (standard PCI card) 
¢ Designed and optimized for RSA encryption 

* Onboard hardware-based RNG (random number generator) 

* Five mounted IBM UltraCypher Cryptographic Engines 


pe) 


See the following information regarding the 2058 Cryptographic Accelerator: 


¢ |Plan for the 2058 Cryptographic Accelerator 
¢ |Configure the 2058 Cryptographic Accelerator 


Cryptographic hardware scenario: Enhance iSeries SSL performance 


To give you an idea of how you can use this cryptographic hardware with your iSeries server, we have 
added this usage scenario. 


Situation 


A company’s iSeries server handles thousands of secured Internet transactions per day. The company’s 
transactions utilize the Secure Sockets layer and Transport Layer Security protocols (SSL and TLS) -— a 
common method for securing Internet transactions. This company’s system administrator, Sue, wants to 
free up server resources for additional application processing, including the ability to support even more 
SSL transactions. Sue is looking for a solution that fits these objectives: 


¢ A sizeable increase in the available server resources for application processing, including additional SSL 
transactions 


¢ Minimal installation and configuration effort 
¢ Minimal resource management requirements 
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Based on these objectives, Sue orders and installs an IBM 2058 e-Business Cryptographic Accelerator. 
(hereafter referred to as a 2058 Cryptographic Accelerator). The 2058 Cryptographic Accelerator is a PCI 
(Peripheral Component Interconnect) card, which is specially designed to accelerate the very compute 
intensive processing required when establishing a SSL/TLS session. On iSeries servers the 2058 
Cryptographic Accelerator can be obtained by ordering hardware feature code 4805. 


Details 


1. The iSeries server has a 2058 Cryptographic Accelerator installed and configured. 
2. The iSeries server receives a high number of SSL transaction requests from the network. 


3. The 2058 Cryptographic Accelerator performs the cryptographic processing in the initiation of SSL 
transactions, and caches the private keys that are associated with the digital certificates for SSL 
transactions. 


Prerequisites and assumptions 


This scenario assumes that Sue has planned for the installation of the 2058 Cryptographic Accelerator, 

aiid neu coctiqured the:card properly (cos Plan or the 2056 Cryatooraphicaccclerator ena confiure teal 
058 Cryptographic Accelerator) This scenario also assumes that Sue has already set up a digital 
certificate for SSL. 


Configuration steps 


Sue completes the following steps to enhance the SSL performance of her company’s iSeries server: 
1. Order Hardware Feature code 4805, which provides the 2058 Cryptographic Accelerator. 
2. Install the 2058 Cryptographic Accelerator. 


3. Create a device description for the 2058 Cryptographic Accelerator, and vary-on the device (see 
Configure the 2058 Cryptographic Accelerator] for details). 
Plan for the 2058 Cryptographic Accelerator 


Your server must meet these requirements before you install and use the 2058 Cryptographic Accelerator. 
Hardware requirements 


The IBM e-Business Cryptographic Accelerator (orderable feature code 4805, and hereafter referred to as 
the 2058 Cryptographic Accelerator). The 4805 feature is a standard PCI card, and is supported on the 
following iSeries server models: 


« 270 

* 810, 820, 825, 830, 840, 870 and 890 

¢ SB2 and SB3 

¢ Expansion units 5074, 5075, 5078, 5079, 5088, 5094, 5095 and 5294 


OS/400 and SSL requirements 
The 2058 Cryptographic Accelerator requires the OS/400 V5R2M0 (Version 5 Release 2 Modification 0) 
software. Although the 2058 Cryptographic Accelerator is fully enabled for cryptographic operations, the 


Cryptographic Access Provider 128—bit (5722—AC3) licensed program product must also be installed on 
the iSeries server to enable the cryptograhic functions in OS/400 that SSL also uses. 
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Configure the 2058 Cryptographic Accelerator 


You must create a device description so that OS/400 SSL can direct RSA cryptographic operations to the 
2058 Cryptographic Accelerator. You can create a device description by using the Create Device Crypto 
CL command. 


Create device description 


To create a device description using the CL command, follow these steps: 
Type CRTDEVCRP at the command line. 

Specify a name for the device as prompted. 

Accept the default name of the PKA key store: “NONE. 

Accept the name default of the DES key store: *NONE. 

Specify a description as prompted. This is optional. 


Use either the Vary Configuration (VRYCFG) or the Work with Configuration Status (WRKCFGSTS) CL 
commands to vary on the device once you have created the device description. 


ouProON = 


For digital certificates that are generated by software, and stored in software, OS/400 SSL automatically 
starts using the 2058 Cryptographic Accelerator once the device is varied-on. The private key processing 
associated with SSL and TLS session establishment is off-loaded to the 2058 Cryptographic Accelerator. 
When the device is varied-off, OS/400 SSL switches back to software based encryption for establishing 
SSL and TLS sessions, thereby placing the private key processing load back on the server. 


Note: This is only true for certificates and private keys that were not created by the 4758 Cryptographic 
Coprocessor. If a certificate was generated using the 4758 Cryptographic Coprocessor, the 4758 
Cryptographic Coprocessor has to be used for those SSL or TLS sessions which use that particular 
certificate. 


The|Cryptographic hardware scenario: Enhance iSeries SSL performance] page offers an iSeries server 


usage scenario for the 2058 Cryptographic Accelerator, once it has been installed and varied on.*& 
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Chapter 5. 4758 Cryptographic Coprocessor for iSeries 


With iSeries servers, you can use the 4758 Coprocessor in the following ways: 


¢ You can use the 4758-023 Coprocessor along with DCM to generate and store private keys associated 
with SSL digital certificates. In addition the 4758-023 Coprocessor provides a performance assist 
enhancement and capability by handling SSL private key processing during SSL session establishment. 


In order to support load balancing and performance scaling, the iSeries server allows the usage of 
multiple (up to eight) 4758-023 Coprocessors with SSL. When using multiple Coprocessors, DCM 
configuration gives you the following options for using hardware to generate and store the private key 
associated with a digital certificate. 


1. Private key generated in hardware and stored (i.e., retained) in hardware. 


With this option the private key never leaves the Coprocessor, and thus the private key cannot be 
used or shared with another Coprocessor. This means that you and your application have to 
manage multiple private keys and certificates. 


2. Private key generated in hardware and stored in software (i.e., stored in a key store file). 


This option allows a single private key to be shared amongst multiple Coprocessors. A requirement 
is that each Coprocessor must share the same master key—you can use|“Clone master keys” on 
page 189]to set up your Coprocessors to have the same master key. The private key is generated in 


one of the Coprocessors and is then saved in the key store file, encrypted under the master key of 
that Coprocessor. Any Coprocessor with an identical master key can use that private key. 


You can use the 4758-023 Coprocessor to implement OS/400 applications. To do this you or an 
applications provider must write an application program, using the CCA CSP APIs to access the 
cryptographic services in the 4758 Coprocessor. Examples of such applications are financial PIN 
processing transactions, bank to clearing house transactions, and basic SET™ block processing. Up to 
eight Coprocessors can be used via the CCA CSP. The application must control access to individual 
Coprocessor by using the Cryptographic_Resource_Allocate (CSUACRA) and 
Cryptographic_Resource_Deallocate (CSUACRD) CCA APIs. 


For more information about your 4758 Coprocessor, refer to the following pages: 


“Features of the 4758 Cryptographic Coprocessor” on page 16 


The 4758 Coprocessor contains hardware engines, which perform cryptographic operations used during 
SSL and OS/400 applications. 


The Common Cryptographic Architecture Cryptographic Service Provider (CCA CSP) is packaged as 
OS/400 Option 35. It provides a security application programming interface (SAPI) to which you can write 
applications that allow you to access the cryptographic services of your 4758 Coprocessor. 


The features page describes in greater detail what the 4758 Coprocessor and CCA CSP have to offer. 


“Requirements for the 4758 Cryptographic Coprocessor” on page 20 


Your server must meet some requirements before you can install and use your 4758 Coprocessor. Use the 
requirements page to determine whether you are ready to install and use your 4758 Coprocessor on your 
server. 


Chapter 3, “Concepts” on page 7 


Depending on your familiarity with cryptography, you may need more information about a term or concept. 
This page introduces you to some basic cryptographic concepts. 


See|Related information| for additional sources of cryptography information recommended by IBM. 
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Features of the 4758 Cryptographic Coprocessor 


The 4758 PCI Cryptographic Coprocessor provides cryptographic processing capability and secure storage 
of cryptographic keys. Cryptographic functions supported include encrypt/decrypt for keeping data 
confidential, message digests and message authentication codes for ensuring that data has not been 
changed, digital signature generate/verify, and financial PIN and SET processing. You can use the 
Coprocessor with OS/400 SSL or with OS/400 applications written by you or an application provider. 


When used with SSL, the Coprocessor can be used to create and store a private key in a FIPS 140-1 
certified hardware module or the Coprocessor can be used to create, encrypt and store a private key 
(encrypted under the master key) in software so the private key can be used by multiple Coprocessor 
cards. Master keys are always stored in the FIPS 140-1 certified hardware module. Additionally, during the 
establishment of an SSL session the Coprocessor will off-load computationally-intensive cryptographic 
processing from the iSeries server main CPU. 


For OS/400 applications, the Common Cryptographic Architecture Cryptographic Service Provider (CCA 
CSP) APIs are used to access the cryptographic and key management functions of the Coprocessor. 


The 4758-023 PCI Cryptographic Coprocessor supports DES, triple-DES, RSA, MD5, SHA-1, 
RIPEMD-160, and financial PIN services. In addition, it supports SET (Secure Electronic Transaction) 
block cryptographic services. The main benefit of the 4758 Coprocessor is that it provides the capability to 
store encryption keys. It does this in a tamper-responding, battery backed-up module, which is also 
referred to as the secure module. The 4758-023 PCI Cryptographic Coprocessor the Federal Information 
Processing Standard (FIPS) PUB 1400-1, Level 3 requirements. Another benefit of the 4758 Coprocessor 
is that it can be used to off-load the iSeries server main CPU from computationally-intensive cryptographic 
processing during the establishment of a SSL session. 


The 4758 Coprocessor provides a role-based access control facility, which allows you to enable and 
control access to individual cryptographic operations supported by the Coprocessor. 


CCA CSP features 


You can use your 4758 Coprocessor with CCA CSP to provide high-level cryptographic security for your 
applications. Customer or third-party applications access these services through a set of application 
programming interfaces (APIs). You can find these APls described in the]IBM 4758 PCI Cryptographic 
Coprocessor CCA Basic Services Reference and Guide 2 The APIs are provided with OS/400 Option 35 


- Common Cryptographic Architecture Cryptographic Service Provider (CCA CSP). 


The 4758 Coprocessor will use the CCA master key to encrypt keys so that you can store those keys 
outside of your 4758 Coprocessor. You store those keys in a key store file, which is a database file. 


IBM’s CCA enables a consistent approach to cryptography on major IBM computing platforms. OS/400 
CCA CSP supports application software that is written in ILE C, RPG, and Cobol. Application software can 
call on CCA services to perform a wide range of cryptographic functions, including Data Encryption 
Standard (DES) and RSA algorithms. 


OS/400 CCA CSP provides API support equivalent to the CCA Support Program that is available for NT, 
AIX® and OS/2®. CCA CSP exploits the capabilities of the 4758 Coprocessor and allows you to do the 
following: 


* Create role-based access controls to define the level of access that you give to your users. 
* Generate random-numbers. 

* Clone a master key securely. 

* Support financial PIN-processing. 

* Generate and validate digital signatures. 
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¢ Encrypt and decrypt data. 

¢ Protect keys. 

¢ Import and export encrypted DES and Triple-DES keys securely. 
* Generate Message Authentication Codes (MAC). 


Cryptographic hardware scenarios for the 4758 Cryptographic 
Coprocessor 


a 


To give you some ideas of how you can use this cryptographic hardware with your iSeries server, we have 
added the following usage scenarios: 


* |Cryptographic hardware scenario: Protect private keys with cryptographic hardware 


This scenario might be useful for a company that needs to increase the security of the iSeries server 
server digital certificate private keys that are associated with the SSL-secured business transactions. 


¢ |Cryptographic hardware scenario: Write an OS/400 application to use the 4758 Cryptographic 
This scenario could help an OS/400 programmer reason through the process of writing a program that 
calls the 4758 Cryptographic Coprocessor to verify user data such as financial personal identification 


numbers (PINs), which are entered at automatic teller machines (ATMs) .%& 


Cryptographic hardware scenario: Protect private keys with 
cryptographic hardware 


ao 


Situation 


A company has an iSeries server dedicated to handling business-to-business (B2B) transactions. This 
company’s iSeries server specialist, Sam, has been informed by management of a security requirement 
from its B2B customers. The requirement is to increase the security of the iSeries server digital certificate 
private keys that are associated with the SSL-secured business transactions that Sam’s company 
performs. Sam has heard that there is a cryptographic hardware option available for iSeries servers that 
both encrypts and stores private keys associated with SSL transactions in tamper-responding hardware: 
The IBM 4758-023 Cryptographic Coprocessor PCI card (Hardware Feature code 4801, or 4802, and 
hereafter referred to as the 4758 Cryptographic Coprocessor). 


Sam researches the 4758 Cryptographic Coprocessor, and learns that he can use it with the OS/400 
Digital Certificate Manager (DCM) to provide secure SSL private key storage, as well as increase iSeries 
server performance by off-loading from the iSeries server the cryptographic operations which are 
completed during SSL-session establishment. 


ryptographic hardware cards on the iSeries}for more information. 


Note: To support load balancing and performance scaling, Sam can use multiple (up to eight) 4758 
Cryptographic Coprocessors with SSL on the iSeries server. See |Implementing multiple 
ryptographic hardware cards on the iSeries 


Sam decides that the 4758 Cryptographic Coprocessor meets his company’s requirement to increase the 
security of his company’s iSeries server. 


Details 
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1. The company’s iSeries server has a 4758 Cryptographic Coprocessor installed and configured to store 
and protect private keys. 


2. Private keys are generated by the 4758 Cryptographic Coprocessor. 
3. Private keys are then stored on the 4758 Cryptographic Coprocessor. 
4. The 4758 Cryptographic Coprocessor resists both physical and electronic hacking attempts. 


Prerequisites and assumptions 


1. The iSeries server has a 4758 Cryptographic Coprocessor installed and configured proper see [Plan] 
or the 4758 Cryptographic Coprocessor| and |Configure the 4758 Cryptographic Coprocessor). 


Planning for the 4758 Cryptographic Coprocessor includes getting SSL running on the iSeries server. 


Note: To use multiple 4758 Cryptographic Coprocessor cards for application SSL handshake 
processing, and securing private keys, Sam will need to ensure that his application can manage 
multiple private keys and certificates. 

2. Sam’s company has Digital Certificate Manager (DCM) installed and configured, and uses it to[Manage| 


public Internet certificates for SSL communications sessions 


3. Sam’s company obtain certificates from a public Certificate Authority (CA). 


4. The 4758 Cryptographic Coprocessor is varied on prior to using DCM. Otherwise, DCM will not provide 
a page for selecting a storage option as part of the certificate creation process. 


Configuration steps 


Sam needs to perform the following steps to secure private keys with cryptographic hardware on his 
company’s iSeries server: 


1. Ensure that the prerequisites and assumptions for this scenario have been met. 


2. Use the IBM Digital Certificate Manager (DCM) to create a new digital certificate, or renew a current 
digital certificate: 


a. Select the type of certificate authority (CA) that is signing the current certificate. 
b. Select the Hardware as your storage option for certificate’s private key. 
c. Select which cryptographic hardware device you want to store the certificate’s private key on. 
d. Select a public CA to use. 
The private key associated with the new digital certificate is now stored on the 4758 Cryptographic 


Coprocessor specified in Step 2.c. Sam can now go into the configuration for his company’s web server 
and specify that the newly created certificate be used. Once he restarts the web server, it will be using the 


new certificate.*& 


Cryptographic hardware scenario: Write an OS/400 application to use 
the 4758 Cryptographic Coprocessor 


a 


Situation 


Suppose you are an iSeries server programmer for a large financial Credit Union. You have been assigned 
the task of getting the IBM 4758-023 Cryptographic Coprocessor PCI card (Hardware Feature code 4801 
or 4802, and hereafter referred to as the 4758 Cryptographic Coprocessor) that is installed in the Credit 
Union iSeries server to verify members’ financial personal identification numbers (PINs) when they are 
entered at automatic teller machines (ATMs). 
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You decide to write an iSeries server OS/400 application program using the CCA CSP (cryptographic 
service provider) APIs that are a part of Option 35 to access the cryptographic services in the 4758 
Coprocessor to verify members’ PINs. iSeries server OS/400 application programs written for the 4758 
Cryptographic Coprocessor utilize the coprocessor to perform security-sensitive tasks and cryptographic 
operations. 


Note: Up to eight 4758 Cryptographic Coprocessors can be used via the CCA CSP. The application must 
control access to individual Coprocessor by using the Cryptographic_Resource_Allocate 
(CSUACRA) and Cryptographic_Resource_Deallocate (CSUACRD) CCA APIs. 


Details 


A Credit Union member enters their PIN at an ATM. 
The PIN is encrypted at the ATM, and then sent along the network to the Credit Union’s iSeries server. 
The iSeries server recognizes the transaction request, and calls a program to verify the member's PIN. 


The program sends a request containing the encrypted PIN, member's account number, 
PIN-generating key, and PIN encrypting key to the 4758 Cryptographic Coprocessor. 


5. The 4758 Cryptographic Coprocessor confirms or denies the validity of the PIN. 

6. The program sends the 4758 Cryptographic Coprocessor’s results to the ATM. 
a. If the PIN is confirmed, the member can successfully complete a transaction with the Credit Union. 
b. If the PIN is denied, the member is unable to complete a transaction with the Credit Union. 


Pen = 


Prerequisites and assumptions 


1. Your company has an iSeries server with a properly installed and configured 4758 Cryptographic 
Coprocessor. Refer to the following information: 


a. |Plan for the 4758 Cryptographic Coprocessor 
b. |Configure the 4758 Cryptographic Coprocessor 
c. |Configure the 4758 Cryptographic Coprocessor for use with OS/400 applications| 


2. You are familiar with Option 35: The Common Cryptographic Architecture Cryptographic Service 
Provider (CCA CSP). It is packaged as OS/400 Option 35, and provides a security application 
programming interface (SAPI) to which you can write applications that allow you to access the 
cryptographic services of the 4758 Cryptographic Coprocessor. 


3. You have access to the |CCA Basic Services Guide 2 , where you can find Financial Services Support 


verbs to use in your application. 


Configuration steps 


One way to accomplish your objective of using the 4758 Cryptographic Coprocessor to validate PINs is to 
write two iSeries server OS/400 applications: 


1. Write a program that loads the both the PIN verification keys, and PIN encrypting keys, and stores 
them in a key store file. Assuming that clear key parts are used, you need to use the following APIs: 


* Logon_Control (CSUALCT) 

* Key_Part_Import (CSNBKPI) 

* Key_Token_Build (CSNBKTB) 

¢ Key_Record_Create (CSNBKRC) 

* Key_Record_Write (CSNBKRW) 

* Optional API: KeyStore_Designate (CSUAKSD) 


2. Write a second program that calls the Encrypted_PIN_Verify (CSNBPVR) API to verify encrypted PINs, 
and then reports their valid or invalid status back to the ATM. 
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| Related page: |Configure the 4758 Cryptographic Coprocessor for use with OS/400 applicationsk 
Plan for the 4758 Cryptographic Coprocessor 


The following information is pertinent to those planning to install a 4758 Cryptographic Coprocessor in an 
iSeries server: 


¢ |Requirements for the 4758 Cryptographic Coprocesso 
¢ |Secure access to the 4758 Cryptographic Coprocessor 
¢ |Object authorities that are required for SAPI 


Requirements for the 4758 Cryptographic Coprocessor 
Your server must meet these requirements before you install and use the 4758 Coprocessor. 


Hardware requirements 


The 4758-023 Coprocessor for iSeries server can be ordered by specifying feature code 4801 or 4802. 
The 4801 feature is supported on the following iSeries server models: 


* 250 and 270 (250 requires the 7102 expansion unit) 

* 810, 820, 825, 830, 840, 870 and 890 

* SB2 and SB3 

* Expansion units 5074, 5075, 5078, 5079, 5088, 5094, 5095 and 5294 


Your 4758 Coprocessor is a PCI card. Install the card as described in the installation manual that came 
with your Coprocessor. 


Note: The 4758 Coprocessor destroys its factory certification if allowed to cool below -15 degrees C (5 
degrees F). If your 4758 Coprocessor destroys its factory certification, you can no longer use the card. 
Contact your hardware service provider about ordering a new card. 


Software requirements 


Your 4758 Coprocessor requires the following software: 

* OS/400 (5722-SS1): the 4758-023 Coprocessor (iSeries server feature codes 4801 or 4802) requires 
OS/400 Version 4 Release 5 Modification 0 or later. 

* OS/400 Option 35 Common Cryptographic Architecture Cryptographic Service Provider (CCA CSP) 

* OS/400 Option 34 Digital Certificate Manager (if you are planning on using 4758 Coprocessor 
configuration web-based utility) 

* OS/400 57xx-TC1 TCP/IP Connectivity Utilities (if you are planning on using 4758 Coprocessor 
configuration web-based utility) 

* OS/400 57xx—DG1 IBM HTTP Server (if you are planning on using 4758 Coprocessor configuration 
web-based utility) 


¢ The Cryptographic Access Provider 128-bit for iSeries server (5722-AC3) licensed program product 
must be installed on your iSeries server to enable the encryption capabilities of the 4758 Cryptographic 
Coprocessor. This option enables your 4758 Coprocessor to use 56-bit DES keys, 112 bit Triple DES 
keys, and 2048-bit RSA keys. 


Notes: 


1. The 4758 Coprocessor configuration web-based utility was new with OS/400 Version 5 Release 2 
Modification 0. 


2. Special, limited availability PTFs must be installed before using the 4758-023 Coprocessor with SSL 
on OS/400 Version 4 Release 5 Modification 0. No special PTFs are required to use the 4758-023 
Coprocessor with SSL on OS/400 Version 5 Release 2 Modification 0, or later releases of OS/400. 
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3. You may have a previous version of a Cryptographic Access Provider (e.g. 5769—AC1, 5769—AC2, 
5769-AC3) installed. These products are compatible with Version 5 Release 2 Modification 0. 


Secure access to the 4758 Cryptographic Coprocessor 


Access control restricts the availability of system resources to only those users you have authorized to 
interact with the resources. The server allows you to control authorization of users to system resources. 
Your organization should identify each system resource in the organization’s security hierarchy. The 
hierarchy should clearly delineate the levels of access authorization users have to resources. 


All of the service programs in OS/400 Option 35 are shipped with *EXCLUDE authority for *~PUBLIC. You 
must give users *USE authority for the service program that they need to use. In addition, you must also 
give users *USE authority to the QC6SRV service program in library QCCA. 


Users who take part in setting up the 4758 Coprocessor must have *IOSYSCFG special authority to use 
the Master_Key_Process (CSNBMKP), Access_Control_Initialize (CSUAACI), or 
Cryptographic_Facility_Control (CSUACFC) security application programming interfaces (SAPIs). These 


three SAPIs are used to perform all configuration steps for the 4758 Coprocessor. For all SAPIs, users 
may require additional object authorities. Refer to |“Object authorities that are required for SAPI” 

For the most secure environments, consider assigning the role of 4758 administrators to a set of users 
who do not have *ALLOBJ special authority. This way, users with *ALLOBJ special authority cannot alter 
the configuration of the Coprocessor because they will not be able to log on to an administrative role on 


the 4758. They can, however, control object authority to the SAPI service programs, preventing misuse by 
the 4758 administrators. 


In order to use the 4758 Cryptographic Coprocessor configuration web utility, users must have *SECADM 
special authority. 


The 4758 Coprocessor has separate access controls which are unrelated to the access controls of the 
server. The 4758 Coprocessor access controls allow you to control access to the 4758 Coprocessor 
hardware commands. For more information about these commands, sos) Cleats and deine toiseand 


For even more security, limit the capabilities of the default role within your 4758 Coprocessor. Assign 
capabilities among other roles to require two or more people to perform security-sensitive functions, like 


changing the master key. You can do this when you work with roles and profiles as described in[‘Create| 
and define roles and profiles” on page 25 


Note: You should consider some standard physical security measures as well, such as keeping your 
server behind a locked door. 


Object authorities that are required for SAPI 


SAPI *USE for *USE for *CHANGE _ |*USE for *USE for *CHANGE _/|*USE for 
device DES for DES DES PKA for PKA PKA 
keystore keystore Keystore keystore keystore Keystore 
Library Library 

CSNBCKI Y Y! Y’ 

CSNBCKM* Y Ye Y 

CSNBCPA Y ¥ 7 

CSNBCPE Y Y! y? 

CSNBCSG* Y a Y" 

CSNBCSV* Y y" 5 
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SAPI 


*USE for 
device 


*USE for 
DES 
keystore 


*CHANGE 
for DES 
keystore 


*USE for 
DES 
Keystore 
Library 


*USE for 
PKA 
keystore 


*CHANGE 
for PKA 
keystore 


*USE for 
PKA 
Keystore 
Library 


CSNBCVE* 


Y! 


yY! 


CSNBCVG* 


CSNBCVT* 


vy! 


Y! 


CSNBDEC 


Y! 


yY! 


CSNBDKG 


Y! 


CSNBDKM 


CSNBDKX 


CSNBKEX 


CSNBKGN 


CSNBKPI 


CSNBKRC 


CSNBKRD 


CSNBKRL 


CSNBKRR 


CSNBKRW 


CSNBKSI 


CSNBKTC 


<|~<|<|<|[<«|«|</|<|/<|/< 


CSNBKTP* 


CSNBKTR 


CSNBKYT 


CSNBMDG* 


CSNBMGN 


CSNBMKP 


CSNBOWH 


CSNBPEX* 


CSNBPGN 


CSNBPTR 


CSNBPVR 


CSNBTRW* 


CSNDDSG 


CSNDKRD 


CSNDKRL 


CSNDKRR 


CSNDKRW 


CSNDKTC 


Y 


Y! 
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SAPI *USE for *USE for *CHANGE _ /|*USE for *USE for *CHANGE _ /|*USE for 
device DES for DES DES PKA for PKA PKA 
keystore keystore Keystore keystore keystore Keystore 
Library Library 
CSNDPKB* 
CSNDPKG Y y" Y" y! 
CSNDPKH Y 
CSNDPKI Y Yi Y? y' 
CSNDPKR Y 
CSNDPKX Y Y" Y! 
CSNDRKD Y 
CSNDRKL Y 
CSNDSBC Y y" Y? 
CSNDSBD Y y! Y' 
CSNDSYG Y ¥! Y" 
CSNDSYI Y Y! Y? a y! 
CSNDSYX Y Y" Y" Y" Y" 
CSUAACI Y 
CSUAACM Y 
CSUACFC Y 
CSUACFQ Y 
CSUACRA Y 
CSUACRD Y 
CSUAKSD 
CSUALCT Y 
CSUAMKD Y 


'Use of Data Encryption Standard (DES) or public key algorithm (PKA) keystore for this API is optional. 


?More than one parameter may optionally use keystore. The authority requirements differ on each of those 
parameters. 


°The Key_Store_Initialize SAPI does not require authority to both files simultaneously. 


4These SAPIs pertain only to the 4758-023 Coprocessor. 


Configure the 4758 Cryptographic Coprocessor 


Configuring your 4758 Coprocessor allows you to begin to use all of its cryptographic operations. 


The easiest and fastest way to configure your 4758 Coprocessor is to use the 4758 Cryptographic 
Coprocessor configuration web-based utility found off of the iSeries server Tasks page at 
http://server-name:2001. The utility includes the Basic configuration wizard that is used for configuring (and 
initializing) a Coprocessor that has not been previously configured. If HTTP and SSL have not been 
previously configured, you will need to do the following before using the Configuration Wizard. 

¢ Start the HTTP Administrative server. 


* Configure the HTTP Administrative server to use SSL. 
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* Use DCM to create a certificate, specifying that the private key be generated and stored in software. 
¢ Use DCM to receive the signed certificate. 

* Associate the certificate with the HTTP Administrative server application ID. 

¢ Re-start the HTTP Administrative server to enable it for SSL processing. 


If the 4758 Coprocessor has already been configured, then click on the Manage configuration option to 
change the configuration for specific portions of the Coprocessor. 


If you would prefer to write your own application to configure the Coprocessor, you can do so by using the 
Cryptographic_Facility_Control (CSUACFC), Access_Control_Initialize (CSUAACI), Master_Key_Process 
(CSNBMKP), and Key_Store_Initialize (CSNBKSI) API verbs. Many of the pages in this section include 
one or more program examples that show how to configure the Coprocessor via an application. Change 
these programs to suit your specific needs. 


Whether you choose to use the 4758 Cryptographic Coprocessor configuration utility or write your own 
applications, the following outlines the steps you must take to properly configure your 4758 Coprocessor: 


1. "Create a device description] The device description specifies a default location for key storage. You 


can create a device description with or without naming any key store files. 


2. |‘Name files to key store file” on page 25} Before you can perform any operation using a key store file 


or key stored in a key store file, you must name the key store file. You can explicitly name key store 
files by using a program, or you can name them on the device description. You name one file to store 
Data Encryption Standard (DES) and Triple—DES keys and another file to store public key algorithm 
(PKA) keys. By naming the files in which to store your keys, you set up that database to contain your 
DES (and Triple-DES) and PKA keys. You should name key store files by using a program if you want 
to keep your keys in your own key store file. If you do not name key store files with a program, the 
CCA CSP will store your keys in the key store file named on the device description. 


3. |‘Create and define roles and profiles” on page 25| When you assign users to these roles and profiles, 


you determine what cryptographic functions your 4758 Coprocessor will allow the users to use. 


4. Set the environment ID and clock” on page 63} Your 4758 Coprocessor uses the EID to verify which 


4758 Coprocessor created a key token. It uses the clock for time and date stamping and to control 
whether a profile can log on. 


5. |“Load a function control vector’ on page 73} The function control vector tells the 4758 Coprocessor 


what key length to use to create keys. You cannot perform any cryptographic functions without loading 
a function control vector. 


6. |‘Load and set a master key” on page 85} After you load a function control vector, load and set the 


master key. You can use your master key to encrypt other keys. 


Create a device description 


You must create a device description for your 4758 Coprocessor on your server. The device description is 
used by CCA CSP to help direct cryptographic requests to the 4758 Coprocessor. Additionally, the device 
description gives your 4758 Coprocessor a default location for key store file storage. The Basic 
configuration wizard in the 4758 Cryptographic Coprocessor configuration utility, found off of the iSeries 
server Tasks page at http://server-name:2001, can create a device description for you, or you can create a 
device description yourself by using the Create Device Crypto CL command. 


To create a device description using the Basic configuration wizard, follow these steps: 

Point your web browser to the iSeries server Tasks page: http://server-name:2001 

Click on 4758 Cryptographic Coprocessor configuration. 

Click on the button labeled Start secure session. 

Click Basic configuration wizard. 

Click continue on the Welcome page. 

Click on the list entry with the device name set to «CREATE for the resource you want to use. 


Oo & ON = 
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7. Continue as instructed by the Basic configuration wizard. 


To create a device description using the CL command, follow these steps: 
1. Type CRTDEVCRP at the CL command line. 


2. Specify a name for the device as prompted. If you want to set up a default device, name the device 
CRP01. Otherwise, each application you create must use the Cryptographic Resource Allocate 
(CSUACRA) API in order to access your device description. 


Specify the name of a default PKA key store file or let the parameter default to «NONE. 
Specify the name of a default DES key store file or let the parameter default to «NONE. 
Specify a description as prompted. This is optional. 


Use either the Vary Configuration (VRYCFG) or the Work with Configuration Status (WRKCFGSTS) CL 
commands to vary on the device once you have created the device description. 


7. This typically takes one minute, but it may take ten minutes to complete. 


oar ow 


You have now completed creation of the device description. 


Name files to key store file 


Before you can perform any operation using a key store file or a key stored in a key store file, you must 
name the key file. This points your 4758 Coprocessor to the correct file. You can name two types of key 
store files. One type stores Data Encryption Standard (DES) keys and Triple-DES keys. DES and Triple 
DES are symmetric cryptographic algorithms; the 4758 Coprocessor uses the same key to encrypt and 
decrypt. The other type stores public key algorithm (PKA) keys. Public key algorithms are asymmetric; 
keys are created in pairs. The 4758 Coprocessor uses one key to encrypt and the other to decrypt. The 
4758 Coprocessor supports the RSA public key algorithm. 


You can name a key store file explicitly by using a program, or you can name it by configuring it on the 
device description. To name a key store file from a program, use the Key_Store_Designate (CSUKSD) 
security application programming interface (SAPI). If you name key store files that use a program, your 
4758 Coprocessor only uses the names for the job that ran the program. However, by naming key store 
files explicitly in your program, you can use separate key store files from other users. If you name key 
store files on the device description, you do not have to name them in your program. This may help if you 
are trying to maintain the same program source across multiple IBM platforms. It is also useful if you are 
porting a program from another implementation of Common Cryptographic Architecture. 


You need to store your cryptographic keys in a secure form so that you can use them over time and 
exchange them with other users and servers, as appropriate. You can store your cryptographic keys by 
using your own methods, or you can store them in a key store file. You can have as many key store files 
as you want, and you can create multiple key store files for each type of key. You can place as many 
cryptographic keys in your key store files as you want. 


Since each key store file is a separate server object, you can authorize different users to each file. You 
can save and restore each key store file at different times. This depends on how often the file’s data 
changes or which data it is protecting. 


Create and define roles and profiles 


The 4758 Coprocessor uses role-based access control. In a role-based system, you define a set of roles, 
which correspond to the classes of 4758 Coprocessor users. You can enroll each user by defining an 
associated user profile to map the user to one of the available roles. 


The capabilities of a role are dependent on the access control points or cryptographic hardware 


commands that are enabled for that role. You can then use your 4758 Coprocessor to create profiles that 
are based on the role you choose. 
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A role-based system is more efficient than one in which the authority is assigned individually for each user. 
In general, you can separate the users into just a few different categories of access rights. The use of 
roles allows you to define each of these categories just once, in the form of a role. 


The role-based access control system and the grouping of permissible commands that you can use are 
designed to support a variety of security policies. In particular, you can set up the 4758 Coprocessor to 
enforce a dual-control, split-knowledge policy. Under this policy no one person should be able to cause 
detrimental actions other than a denial-of-service attack, once the 4758 Coprocesor is fully activated. To 
implement this policy, and many other approaches, you need to limit your use of certain commands. As 
you design your application, consider the commands you must enable or restrict in the access-control 
system and the implications to your security policy. 


Every 4758 Coprocessor must have a role called the default role. Any user that has not logged on to the 
4758 Coprocessor will operate with the capabilities defined in the default role. Users who only need the 
capabilities defined in the default role do not need a profile. In most applications, the majority of the users 
will operate under the default role, and will not have user profiles. Typically, only security officers and other 
special users need profiles. 


When the 4758 Coprocessor is in an uninitialized state, the default role has the following access control 
points enabled: 


* PKAQ96 One Way Hash 

* Set Clock 

* Reinitialize Device 

* Initialize access control system roles and profiles 
¢ Change the expiration data in a user profile 

* Reset the logon failure count in a user profile 

* Read public access control information 

* Delete a user profile 

* Delete a role 


The default role is initially defined such that the functions permitted are those functions that are related to 
access control initialization. This guarantees that the 4758 Coprocessor will be initialized before you do 
any useful cryptographic work. The requirement prevents security “accidents” in which someone might 
accidentally leave authority intact when you put the 4758 Coprocessor into service. 


Defining roles 


The easiest and fastest way to define new roles (and re-define the default role) is to use the 4758 
Cryptographic Coprocessor configuration web-based utility found off of the iSeries server Tasks page at 
http://server-name:2001. The utility includes the Basic configuration wizard that is used when the 
Coprocessor is in an uninitialized state. The Basic configuration wizard can define either 1 or 3 
administrative roles along with re-defining the default role. If the 4758 Coprocessor already has been 
initialized, then click on Manage configuration and then click on Roles to define new roles or change or 
delete existing ones. 


If you would prefer to write your own application to manage roles, you can do so by using the 
Access_Control_Initialization (CSUAACI) and Access_Control_Maintenance (CSUAACM) API verbs. To 
change the default role in your 4758 Coprocessor, specify "DEFAULT” encoded in ASCII into the proper 
parameter. You must pad this with one ASCII space character. Otherwise, there are no restrictions on the 
characters that you may use for role IDs or profile IDs. Four example programs are provided for your 
consideration. Two of them are written in ILE C, while the other two are written in ILE RPG. Both sets 
perform the same function. 


¢ |“Example: ILE C program for creating roles and profiles for your 4758 Coprocessor” on page 29 
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¢ |“Example: ILE C program for enabling all access control points in the default role for your 4758 


Coprocessor” on page 50 


¢ |“Example: ILE RPG program for creating roles or profiles for your 4758 Coprocessor” on page 41 
¢ |“Example: ILE RPG program for enabling all access control points in the default role for your 4758 


Coprocessor’” on page 54 


Note: If you choose to use one of the program examples provided, change it to suit your specific needs. 
For security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Defining profiles 


After you create and define a role for your 4758 Coprocessor, you can create a profile to use under this 
role. A profile allows users to access specific functions for your 4758 Coprocessor that may not be enabled 
for the default role. 


The easiest and fastest way to define new profiles is to use the 4758 Cryptographic Coprocessor 
configuration web-based utility, located on the iSeries server Tasks page at http://server-name:2001. The 
utility includes the Basic configuration wizard that is used when the Coprocessor is in an uninitialized state. 
The Basic configuration wizard can define either one or three administrative profiles. If the 4758 
Coprocessor has already been initialized, click Manage configuration—>Profiles to define new profiles or 
change or delete existing ones. 


If you want to write your own application to manage profiles, you can use the Access_Control_lInitialization 
(CSUAACI) and Access_Control_Maintenance (CSUAACM) API verbs. Two example programs are 
provided for you: 


* |“Example: ILE C program for changing an existing profile for your 4758 Coprocessor’ on page 58 
* |“Example: ILE RPG program for changing an existing profile for your 4758 Coprocessor’” on page 60 


Note: If you choose to use one of the program examples provided, change it to suit your specific needs. 
For security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


If you will be using the 4758 Coprocessor for SSL, the default role must at least be authorized to the 
following access control points: 


* Digital Signature Generate 
* Digital Signature Verify 

¢ PKA Key Generate 

« PKA Clone Key Generate 
* RSA Encipher Clear Data 
* RSA Decipher Clear Data 
* Delete Retained Key 

¢ List Retain Keys 


The Basic configuration wizard in the 4758 Cryptographic Coprocessor configuration utility automatically 
re-defines the default role such that it can be used for SSL without any changes. 


To avoid security hazards, consider denying the following access control points (also called cryptographic 
hardware commands) for the default role, after you have set up all of the roles and profiles: 


Note: You should enable only those access control points that are necessary for normal operations. At a 
maximum, you should only enable specifically required functions. To determine which access 
control points are required, refer to the CCA Basic Services Guide. Each API lists the access 
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control points that are required for that API. If you do not need to use a particular API, consider 
disabling the access control points that are required for it. 


* Load first part of Master Key 

* Combine Master Key Parts 

¢ Set Master Key 

* Generate Random Master Key 
* Clear New Master Key Register 
* Clear Old Master Key Register 
* Translate CV 

* Set Clock 


Attention: If you intend to disable the Set Clock access control point from the default role, ensure that 
the clock is set before you disable access. The clock is used by the 4758 Coprocessor when users try 
to log on. If the clock is set incorrectly, users can not log on. 


* Reinitialize device 

¢ Initialize access control system 

¢ Change authentication data (for example, passphrase) 

¢ Reset password failure count 

¢ Read Public Access Control Information 

¢ Delete user profile 

* Delete role 

* Load Function Control Vector 

¢ Clear Function Control Vector 

* Force User Logoff 

* Set EID 

¢ Initialize Master Key Cloning Control 

* Register Public Key Hash 

* Register Public Key, with Cloning 

¢ Register Public Key 

¢ PKA Clone Key Generate (Access control point required for SSL) 
* Clone-Information Obtain Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
* Clone-Information Install Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
¢ Delete retained key (Access control point required for SSL) 

¢ List retained keys (Access control point required for SSL) 

* Encipher Under Master Key 

* Data Key Export 

* Data Key Import 

¢ Reencipher to Master Key 

¢ Reencipher from Master Key 

* Load First Key Part 

* Combine Key Parts 

¢ Add Key Part 

* Complete Key part 


For the most secure environment, consider locking the access-control system after initializing it. You can 


render the access-control system unchangeable by deleting any profile that would allow use of the Access 
Control Initialization or the Delete Role acess control point. Without these access control points, further 
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changes to any role are not possible. With authority to use either the Initialize Access Control or Delete 
Role access control points, one can delete the DEFAULT role. 


Deleting the DEFAULT role will cause the automatic recreation of the initial DEFAULT role. The initial 
DEFAULT role permits setting up any capabilities. Users with access to these access control points have 
unlimited authority through manipulation of the access-control system. Before the 4758 Coprocessor is put 
into normal operation, the access-control setup can be audited through the use of the 
Access_Control_Maintenance (CSUAACM) and Cryptographic_Facility_Query (CSUACFQ) API verbs. 


If for any reason the status response is not as anticipated, the 4758 Coprocessor should not be used for 
application purposes until it has been configured again to match your security policy. If a role contains 
permission to change a passphrase, the passphrase of any profile can be changed. You should consider if 
passphrase changing should be permitted and, if so, which role(s) should have this authority. 


If any user reports an inability to log on, this should be reported to someone other than (or certainly in 
addition to) an individual with passphrase-changing permission. Consider defining roles so that dual-control 
is required for every security sensitive operation to protect against a malicious insider acting on his/her 
own. For example, consider splitting the following groups of access control points between two or more 
roles. It is recommended that one person should not be able to use all of the commands in the Master key 
group, because this could represent a security risk. 


The Master key group consists of these access control points: 
¢ Load ist part of Master Key 

* Combine Master Key Parts 

¢ Set Master Key 

* Generate Random Master Key 

* Clear New Master Key Register 

* Clear Old Master Key Register 


By the same token, one person should not be authorized to all of the commands in the Cloning key group. 


The Cloning key group consists of these access control points: 

* Initialize Master Key Cloning Control 

¢ Register Public Key Hash 

* Register Public Key, with Cloning 

¢ Register Public Key 

¢ PKA Clone Key Generate 

¢ Clone-Information Obtain Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 
* Clone-Information Install Parts 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 


After you create and define a profile for your 4758 Coprocessor, you must load a function control vector for 
your 4758 Coprocessor as described in|“Load a function control vector’ on page 73} Without the function 
control vector, your 4758 Coprocessor cannot perform any cryptographic functions. 


Example: ILE C program for creating roles and profiles for your 4758 Coprocessor 
Change this program example to suit your needs for creating a role or a profile for your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


/#aseesessesnesceseenesserssnaSetSsse Sse see eee esse keene ease eeesese */ 
/* CRTROLEPRF x/ 
/* x/ 
/* Sample program to create roles and profiles in the 4758 x/ 
/* cryptographic adapter. x/ 
/* x/ 
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/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: */ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CRTROLEPRF) */ 
/* x/ 
/* Use these commands to compile this program on iSeries server: 

/* CRTCMOD MODULE(CRTROLEPRF) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CRTROLEPRF) MODULE(CRTROLEPRF) */ 
/* BNDSRVPGM(QCCA/CSUAACI QCCA/CSNBOWH) x/ 
/* x/ 
/* Note: Authority to the CSUAACI and CSNBOWH service programs x/ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verbs used are */ 
/* Access Control_Initialization (CSUAACI) and */ 
/* One_Way Hash (CSNBOWH). */ 
/* x/ 
/* Note: This program assumes the device you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
/* Note: Before running this program, the clock in the 4758 must be */ 
/* set using Cryptographic_Facility Control (CSUACFC) in order */ 
/* to be able to logon afterwards. x/ 
/* x/ 
ee ee a a ere */ 
#include "csucincl.h" /* header file for CCA Cryptographic 

Service Provider for iSeries 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


void main(int argc, char *argv[]) { 


#define ERROR -l 
#define OK 0 
#define WARNING 4 


/* Variables used for parameters on CCA APIs 
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*/ 


| ee ee ee eee ee eee ee */ 
long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 
long verb_datal_length; 
long verb_data2_length; 
long hash_length; 
long text_length; 
char «text; 
char chaining_vector[128] ; 
long chaining _vector_length; 
[eaece Seabee ee sse eee oe eee eet ee eae Se see eee eee eee See ee ease Seeeee «/ 
/* Definitions for profiles */ 
[Reece sashes SS SeaSesease eee eee see se eee see aces ae sae eee see ce ssess */ 
typedef struct 
char version[2]; /* Profile structure version */ 
short length; /* length of structure x/ 
char comment [20] ; /* Description */ 
short checksum; 
char logon_failure_count; 
char reserved; 
char userid[8] ; /* Name for this profile */ 
char role[8]; /* Role that profile uses */ 
short act_year; /* Activation date - year */ 
char act_month; /* Activation date - month x/ 
char act_day; /* Activation date - day */ 
short exp_year; /* Expiration date - year */ 
char exp_month; /* Expiration date - month */ 
char exp_day; /* Expiration date - day */ 
short total_auth_data_length; 
short field_type; 
short auth_data_length_l; 
short mechanism; /* Authentication mechanism */ 
short strength; /* Strength of mechanism x/ 
short mech_exp_year; /* Mechanism expiration - year*/ 
char mech_exp_month; /* Mech. expiration - month = */ 
char mech_exp_day; /* Mechansim expiration - day */ 
char attributes [4]; 
char auth_data[20]; /* Secret data */ 
} profile_T; 
typedef struct 
long number; /* Number profiles in struct */ 
long reserved; 
profile T  profile[3]; 
} aggregate_profile; 
aggregate_profile * verb_datal; /* Aggregate structure for */ 
/* defining profiles */ 
[Pessseossos sosaassasecee as sse Sse sscsee snes s asses seeSesssasecseescoss «/ 
/* Definitions for roles x/ 
[eeseseeseaceepeeaseasate a eeseeseesesseceeesesasseeee sae esceeceeseees */ 
[Mosessease se eoeee see ssean cases ese seasons sa ase ones caseeeeeees */ 
/* Default role - access control points list - */ 
/* authorized to everything EXCEPT: */ 
/*  0x0018 - Load 1st part of Master Key x/ 
/* Qx0019 - Combine Master Key Parts x/ 
/*  @xOQO1A - Set Master Key x/ 
/* @x0020 - Generate Random Master Key */ 
/* @x0032 - Clear New Master Key Register */ 


Chapter 5. 4758 Cryptographic Coprocessor for iSeries 


31 


/*  0x0033 - 


/*  0x0053 - 
/*  0x0054 - 
/*  @0x0057 - 
/*  0x0060 - 
/*  0x0061 - 
/*  Qx0110 - 
/*  Qx0111 - 
/*  Qx0112 - 
/*  Qx0113 - 
/* 0x0114 - 
/*  @x0115 - 
/*  0x0116 - 
/*  Qx0117 - 
/*  Qx0118 - 
/*  0x0119 - 
/* OxO11A - 
/*  Qx011B - 
/*  0x0200 - 
/*  Qx0201 - 
/*  0x0202 - 
/*  0x0203 - 
/*  Qx0204 - 
/*  Qx0211 - 


/* For access 


char default_ 


{ 0x00, 0 
0x80, 0 
0x00, 0 
0x10, 0 
OxFF, 0 


/* For access 
char default2 


{ 0x00, 0 
/* role #1 - 
/* 
/*  0x0018 - 
/*  0x0020 - 
/*  0x0032 - 
/*  0x0053 - 
/*  0x0060 - 
/*  0x0119 - 
/*  x0201 - 
/*  0x0202 - 
/*  0x0203 - 
/*  0x0204 - 
/*  Qx0211 - 
/*  Qx0221 - 


char rolel_bi 
{ 0x00, 0 
0x80, 0 

0x00, 0 

0x10, 0 

OxFF, 0 

char rolel_bi 
{ 0x78, 0 


/* role #2 - 
/* 

/*  0x0019 - 
/*  QxOO1A - 


Clear Old Master Key Register 

Load 1st part of PKA Master Key 
Combine PKA Master Key Parts 

Set PKA Master Key 

Clear New PKA Master Key Register 
Clear Old PKA Master Key Register 

Set Clock 

Reinitialize device 

Initialize access control system 
Change user profile expiration date 
Change authentication data (eg. passphrase) 
Reset password failure count 

Read Public Access Control Information 
Delete user profile 

Delete role 

Load Function Control Vector 

Clear Function Control Vector 

Force User Logoff 

Register PKA Public Key Hash 

Register PKA Public Key, with cloning 
Register PKA Public Key 

Delete Retained Key 

PKA Clone Key Generate 

Ox21F - Clone information - obtain 1-15 


control points 0x01 - 0x127 */ 
bitmap[] = 
x03, OxFO, Ox1D, Ox00, 0x00, 0x00, Ox00, 
x00, Ox00, Ox00, Ox00, 0x00, 0x00, 0x00, 
xQA, 0x80, Ox00, 0x88, Ox2F, 0x71, 0x10, 
x04, 0x03, 0x31, 0x80, 0x00, 0x00, Ox00, 
x7F, 0x40, O0x6B, 0x80}; 


control points 0x200 - 0x23F */ 


_bitmap[] = 


X00, 0x00, Ox00, Ox00, OxOO, OxE6, OXOF }; 


authorized to same as default plus also 
authorized to: 

Load 1st part of Master Key 

Generate Random Master Key 

Clear New Master Key Register 

Load 1st part of PKA Master Key 

Clear New PKA Master Key Register 

Load Function Control Vector 

Register PKA Public Key, with cloning 
Register PKA Public Key 

Delete Retained Key 

PKA Clone Key Generate 

0x215 - Clone information - obtain 1-5 
0x225 - Clone information - install] 1-5 


tmap[] = 

x03, OxFO, Ox9D, 0x80, 0x00, 0x20, 0x00, 
x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x00, 
xOA, 0x80, 0x00, 0x88, Ox1F, 0x71, 0x10, 
x04, 0x03, Ox11, Ox80, 0x00, 0x00, Ox00, 
x7F, 0x00, Ox4F, 0x80}; 

tmap2[] = 

x00, Ox7C, 0x00, Ox7C, Ox00, OXE6, OxOF }; 


authorized to same as default plus also 
authorized to: 

Combine Master Key Parts 

Set Master Key 
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*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 


/* x0033 - Clear Old Master Key Register */ 
/* Qx0054 - Combine PKA Master Key Parts */ 
/*  @x0057 - Set PKA Master Key */ 
/* @x0061 - Clear Old Master Key Register */ 
/*  @x011A - Clear Function Control Vector */ 
/* @x0200 - Register PKA Public Key Hash */ 
/*  @x0201 - Register PKA Public Key, with cloning x/ 
/*  0@x0203 - Delete Retained Key */ 
/* Qx0204 - PKA Clone Key Generate x*/ 
/*  @x0216 - 0x21A - Clone information - obtain 6-10 x/ 
/*  @x0226 - 0x22A - Clone information - install 6-10 x/ 
| a ee a eee ee ee */ 
char role2_bitmap[] = 
{ 0x00, 0x03, OxFO, Ox7D, 0x80, 0x00, 0x10, 0x00, 
0x80, 0x00, 0x09, Ox00, 0x40, 0x00, 0x00, 0x00, 
0x00, OxOA, 0x80, 0x00, 0x88, Ox1F, 0x71, 0x10, 
0x10, 0x04, 0x03, 0x31, 0x80, 0x00, 0x00, 0x00, 
OxFF, Ox7F, 0x00, Ox2F, 0x80}; 
char role2_bitmap2[] = 
{ 0xD8, 0x00, 0x03, OxEO, 0x03, OxEO, OxE6, OxOF }; 
| ee a re */ 
/* role #3 - authorized to same as default plus also x/ 
/* authorized to: x/ 
/*  @x@110 - Set Clock x/ 
/*  Qx@111 - Reinitialize device x/ 
/*  @x0112 - Initialize access control system */ 
/* @x0113 - Change user profile expiration date */ 
/*  x0114 - Change authentication data (eg. passphrase) */ 
/*  @x0115 - Reset password failure count */ 
/* @x0116 - Read Public Access Control Information */ 
/* @x0117 - Delete user profile */ 
/*  @x0@118 - Delete role x/ 
/*  x011B - Force User Logoff x/ 
/*  @x0200 - Register PKA Public Key Hash */ 
/*  @x0201 - Register PKA Public Key, with cloning */ 
/*  0x0203 - Delete Retained Key */ 
/* Qx0@204 - PKA Clone Key Generate */ 
/*  @x021B - 0x21F - Clone information - obtain 11-15 */ 
/*  @x022B - Ox22F - Clone information - install 11-15 */ 
[eecnaeeeseneess seseeGeeeee a eeeee ee seeee ees sese se se eseeceseesee */ 
char role3_bitmap[] = 
{ 0x00, 0x03, OxFO, Ox1D, Ox00, Ox00, 0x00, 0x00, 
0x80, 0x00, 0x00, 0x00, OxCO, Ox00, 0x00, 0x00, 
0x00, OxOA, 0x80, 0x00, 0x88, Ox1F, 0x71, 0x10, 
0x10, 0x04, 0x03, 0x31, 0x80, 0x00, 0x00, 0x00, 
OxFF, Ox7F, OxFF, Ox9F, 0x80}; 
char role3_bitmap2[] = 
{ 0xD8, 0x00, 0x00, Ox1F, Ox00, Ox1F, OxE6, OxOF }; 
[RetseSeeseee sae ee eee See eehe oper eeseHeee eee ee Selene anes cease ese */ 
/* Structures for defining the access control points in a role */ 
[Reet eecedesesess eat ees ness see aa See esas esse ae aaa ae oa oaee */ 


struct access_control_points_ header 


{ 


short number_segments; 


/* Number of segments of */ 


/* the access points map */ 


short reserved; 
} access _control_points header; 


struct access _control_points_segment_header 


{ 


short start_bit; /* Starting bit in this */ 

/* segment. */ 
short end_bit; /* Ending bit */ 
short number_bytes; /* Number of bytes in */ 


/* this segment 


*/ 
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short reserved; 
} access_control_points_segment_header; 


| a eee ee ea ee ee eee */ 
/* Structure for defining a role x*/ 
[eee sseneeseesesessessessesecssosstssesssaseseeesesssesatssceee */ 
struct role_header 

{ 

char version[2]; 

short length; 

char comment [20] ; 

short checksum; 

short reservedl; 

char role[8]; 

short auth_strength; 

short lower_time; 

short upper_time; 

char valid_days_of_week; 

char reserved2; 

} role_header; 
| ee eee ee */ 
/* Structure for defining aggregate roles */ 
/ eeacsscussseesessastsseessessesseeeeseecssetseesgsssss4s—5ssoue5 */ 
struct aggregate_role_header 

long number; 

long reserved; 


} aggregate_role_header; 


char * verb_data2; 


char * work_ptr; 
char *bitmapl, *bitmap2; 


int i; /* Loop counter */ 
[ieeusaeen=eeeesacosesssese see ase ese es ae sae sseeeoesaa=es---ssese */ 
/* >>>>>>>> Start of code <<<<<<<<<<<<<<<<<< */ 
| ea ae ee ee */ 
[#esneeeeieke sepa seem eet ees see terse Se eae teen see eset et eee «/ 
/* Allocate storage for the aggregate role structure x/ 
[xees cease saeses aeesesseceesee eee se cra a saeeeesseeeese=-=--==ea= */ 


verb_data2 = malloc(sizeof(aggregate_role header) + 
sizeof(role header) * 3 + 
sizeof (access control _points_header) * 3 + 
sizeof(access_control_points_segment_header) 
«6 + /* 3 roles * 2 segments each */ 
sizeof (default_bitmap) * 3 + 
sizeof (default2_bitmap) * 3); 


work_ptr = verb_data2; /* Set working pointer to 
start of verb data 2 storage */ 


aggregate_role_header.number 


= 3; /* Define/replace 3 roles */ 
aggregate_role_header.reserved = 


0; 
/* Copy header into verb data 
2 storage. x*/ 
memcpy (work_ptr, (void*) &aggregate_role_header, 
sizeof (aggregate role header) ); 


/* Adjust work pointer to point 
after header. x/ 
work_ptr += sizeof (aggregate_role header) ; 


/* Fill in the fields of the role definitions. */ 
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/* Each role is version 1, has authentication strength of 0, */ 
/* has valid time from 12:00 Midnight (0) to 23:59 (x173B), */ 


/* is valid every day of the week. (xFE is 7 bits set), */ 
/* has one access control points segment that starts at bit 0 */ 
/* and goes to bit x11F, and has 20 spaces for a comment. x/ 
Rees eesssesossessessetseessusscesesteese beeSacsseseeacesseceses */ 
role_header.version[0] = 1; 


role_header.version[1] 


0; 
role_header. length i 


sizeof(role_ header) + 
sizeof(access control points _header) + 

2 * sizeof(access control points segment_header) + 

sizeof (default_bitmap) + sizeof (default2_bitmap); 


role_header.checksum = 0; 
role_header.reserved1 = 0; 
role_header.auth_strength = 0; 
role_header.lower_time = 0; 
role_header.upper_time = 0x173B; 
role_header.valid_days_of_week = QOxFE; 
role_header.reserved2 = 0; 


memset (role_header.comment,' ', 20); 


access _control_points_header.number_segments = 2; 
access_control_points_header.reserved = 0; 
access _control_points_segment_header.reserved = 0; 
for (i=0; i<3; i++) 
{ 
switch (i) { 
/xeeesssesscssounsesessssesssssesises shes sssesosee */ 
/* Set name for ROLE1 */ 
[xeeen eee soesoseetee ose eases Sees eee eee ese See */ 
case 0: 
memcpy(role_header.role, "ROLE1 ", 8); 
bitmapl = rolel_bitmap; 
bitmap2 = rolel_bitmap2; 
break; 
/eosssssesecescuesssessssesssssesises shes sssososce */ 
/* Set name for ROLE2 */ 
[eeeeeeeeseecse stesso sseeaeese ese See eeoee ces */ 
case 1: 
memcpy(role_header.role, "ROLE2 ", 8); 
bitmapl = role2_bitmap; 
bitmap2 = role2_bitmap2; 
break; 
/ Saeeseeeseusemes ses sas ==essSsseoeces—s-—s=oss45=5 */ 
/* Set name for ROLE3 x*/ 
| eeseosee eee esos se ans see ee eee ssa ese assesses aaes */ 
case 2: 
memcpy(role_header.role, "ROLE3 ", 8); 
bitmapl = role3_bitmap; 
bitmap2 = role3_bitmap2; 
} 
Jeesssssecenseass Seene -SSsos- ss scssessessssscssessess x/ 
/* Copy role header */ 
[feeserestenecsseoeeeaeeee ses ees eos scseeseaeaceeeoeeS */ 


memcpy (work_ptr, (void*)&role header, sizeof(role_header)); 


/* Adjust work pointer to 
point after role header. */ 
work_ptr += sizeof(role_header) ; 


/* Copy access control points header */ 
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memcpy (work_ptr, 
(void *)&access_control_points header, 
sizeof (access control _points_header)); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access_control_points_header) ; 


[#etemseacsaceseosesseecesseceaneedssssas>eo--e=—ee5 «/ 
/* Copy access control points segment 1 x/ 
| ee ee eee ee «/ 
access _control_points_segment_header.start_bit = 0; 

access _control_points_segment_header.end_bit = 0x127; 


access _control_points_segment_header.number_bytes = 
sizeof (default_bitmap) ; 
memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
sizeof (access _control_points_segment_header)) ; 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access control_points_segment_header) ; 


[Ba deeeesceaasseosds seacesseceaneae esses oes oaaeeeseees «/ 
/* Copy access control points segment 1 bitmap */ 
[eseeeesses en esScnacesetasssscassascsesosa=saseesnaes «/ 


memcpy(work_ptr, bitmapl, sizeof(default_bitmap)); 


/* Adjust work pointer to 
point after bitmap. */ 
work_ptr += sizeof (default_bitmap) ; 


/#osscesssseecssasceseesesesSsscaseesese soeseasseseses «/ 
/* Copy access control points segment 2 */ 
[hoteceeese Se seats aSace ae seer ee de ese ses Sees eeee «/ 
access _control_points segment_header.start_bit = 0x200; 
access _control_points_segment_header.end_bit = Ox23F; 


access _control_points_segment_header.number_bytes = 
sizeof (default2_bitmap); 


memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
sizeof (access _control_points_segment_header)) ; 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access_control_points_segment_header) ; 


PRee ee saeeseeee sears eesenee seen cone sceeseee oes es suee= «/ 
/* Copy access control points segment 2 bitmap */ 
| PaseckesSeseescesseeelescassasssensesssacsesscescass «/ 


memcpy(work_ptr, bitmap2, sizeof(default2_bitmap)); 


/* Adjust work pointer to 
point after bitmap. */ 
work_ptr += sizeof (default2_bitmap); 


[RseecasesaGe ses seSsee sea seas see ae ees es ses aes Se eeees = -a=esee «/ 
/* Allocate storage for aggregate profile structure x/ 
| ee ee eee ee eee «/ 


verb_datal = malloc(sizeof(aggregate_profile)); 


verb_datal->number = = 3; /* Define 3 profiles x/ 
verb_datal->reserved 0; 


36 iSeries: Cryptographic hardware 


fo 
{ 


Se a ee eee ee ee «/ 
Each profile: */ 
will be version 1, */ 
have an activation date of 1/1/00, x*/ 
have an expiration date of 6/30/2005, x*/ 
use passphrase hashed with SHA1 for the mechanism (0x0001), */ 
will be renewable (attributes = 0x8000) */ 
and has 20 spaces for a comment */ 
See pesoeateese see see cca ceost esses stokes se See ose c ees Ss scccse Ss «/ 
r (i=0; i<3; i++) 
verb_datal->profile[i].length = sizeof (profile_T); 
verb_datal->profile[i].version[0] = 1; 
verb_datal->profile[i].version[1] = 0; 
verb_datal->profile[i].checksum = 0; 
verb_datal->profile[i].logon_failure_count = 0; 
verb_datal->profile[i].reserved = 0; 
verb_datal->profile[i].act_year = 2000; 
verb_datal->profile[i].act_month = 1; 
verb_datal->profile[i].act_day = 1; 
verb_datal->profile[i].exp_year = 2005; 
verb_datal->profile[i].exp_month = 6; 
verb_datal->profile[i].exp_day = 30; 
verb_datal->profile[i].total_auth_data_length = 0x24; 
verb_datal->profile[i].field_type = 0x0001; 
verb_datal->profile[i].auth_data_length_1 = 0x20; 
verb_datal->profile[i] .mechanism = 0x0001; 
verb_datal->profile[i].strength = 0; 
verb_datal->profile[i].mech_exp_year = 2005; 
verb_datal->profile[i].mech_exp_month = 6; 
verb_datal->profile[i].mech_exp_day = 30; 
verb_datal->profile[i].attributes [0] = 0x80; 
verb_datal->profile[i].attributes[1] = 0; 
verb_datal->profile[i].attributes [2] = 0; 
verb_datal->profile[i].attributes [3] = 0; 
memset (verb_datal->profile[i].comment, ' ', 20); 
memcpy(rule_array, "SHA-1 ", 8); 
rule_array_count als 
chaining_vector_length = 128; 
hash_length = 20; 
switch (i) { 
[eeeseeesessesseoeteceose sees ees ee= sees */ 
/* Set name, role, passphrase of profile 1 */ 
/ Hoseeeeeeesoeceseaeeeestaeoseesecsessesasese */ 
case 0: 
memcpy(verb_datal->profile[i].userid,"SECOFR1 ",8); 
memcpy(verb_datal->profile[i].role, "ROLE1  ",8); 
text_length = 10; 
text = "Is it safe"; 
break; 
/ fosessesasaasseee seas esse ereessasseasea=stss */ 
/* Set name, role, passphrase of profile 2. */ 
[#eSesicosessecssceseceecssesesisecessscesscsse */ 


case 1: 


memcpy(verb_datal->profile[i].userid,"SECOFR2 ",8); 


memcpy(verb_datal->profile[i].role, "ROLE2 ",8); 

text_length = 18; 

text = "I think it is safe"; 

break; 
fRatieersnesssssssesesseSn soaceae ass cee-eeres */ 
/* Set name, role, passphrase of profile 3 */ 
| #2seeseeseaeasaeas= es =asaeSseeseese=eeseser= */ 

case 2: 
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memcpy (verb_datal->profile[i].userid,"SECOFR3 ",8); 
memcpy(verb_datal->profile[i].role, "ROLE3 ",8); 


text_length = 12; 


text = "Is what safe"; 
} 
[eoebesscetcesessecesaesneecseccecscesisscacs 
/* Call One _Way_Hash to hash the pass-phrase 
[#eosaatesersscesassase sscsssssessossscsssuss 


CSNBOWH( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char*)rule_array, 
&text_length, 
text, 
&chaining_vector_length, 
chaining_vector, 
&hash_length, 
verb_datal->profile[i].auth_data); 


/* Call Access Control Initialize (CSUAACI) to create */ 


/* the roles and profiles. 


rule_array_count = 2; 

memcpy(rule_array, "“INIT-AC REPLACE ", 16); 
verb_datal_length = sizeof(aggregate_ profile); 
verb_data2_length 


sizeof(role header) * 3 + 


*/ 


sizeof (aggregate role header) + 


sizeof (access control points header) * 3 + 
sizeof(access_control_points_segment_header) 
«6 + /* 3 roles * 2 segments each */ 
sizeof (default_bitmap) * 3 + 


sizeof (default2_bitmap) * 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
(long *) &verb_datal_length, 
(char *) verb _datal, 
(long *) &verb_data2_length, 
(char *) verb _data2); 


if (return_code > WARNING) 
printf("Access Control Initialize failed. 
%d/%d\n", return_code, reason_code) ; 
else 
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Return/reason codes: \ 


printf("The new roles and profiles were successfully created\n"); 


/* The Access_Control_Initialize SAPI verb needs to be */ 
/* called one more time to replace the DEFAULT role so that */ 


/* a user that does not log on is not able to 


change any */ 


/* settings in the 4758. x/ 
[eseecia Sea ee saree aseeseceeoee ceeeee esses aes Heese eeease noes */ 
work_ptr = verb_data2; /* Set working pointer to 


start of verb data 2 storage */ 


aggregate_role header.number = 1; /* Define/replace 1 roles */ 


aggregate_role _header.reserved = 0; 
memcpy (work_ptr, (void*) &aggregate_role_header, 
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sizeof (aggregate role header) ); 


/* Adjust work pointer to 
point after header. »*/ 
work_ptr += sizeof (aggregate_role_ header) ; 


/* Fill in the fields of the role definitions. x/ 
/* Each role is version 1, has authentication strength of 0,  */ 
/* has valid time from 12:00 Midnight (0) to 23:59 (x173B), */ 


/* is valid every day of the week. (xFE is 7 bits set), x*/ 
/* has one access control points segment that starts at bit 0 */ 
/* and goes to bit x11F, and has 20 spaces for a comment. x/ 
/xesecseecasossssetescuscreesessossaseesessessesscessqesssedeses */ 


role_header.version[0] 1 
role_header.version[1] 0; 
role_header. length = sizeof(role_header) + 
sizeof(access control points header) + 
2 * sizeof(access control points segment_header) + 
sizeof (default_bitmap) + sizeof (default2_bitmap); 
role_header. checksum = 0; 
role_header.reserved1 
role_header.auth_strength 
role_header.lower_time 7 
role_header.upper_time 
role_header.valid_days_of_week 
role_header.reserved2 = 
memset (role _header.comment,' ', 20); 


access_control_points_header.number_segments = 2; 
access_control_points_header.reserved = 0; 
access_control_points_segment_header.reserved = 0; 


/* DEFAULT role id must be in */ 
/* ASCII representation. */ 
memcpy(role_header.role, "\x44\x45\x46\x41\x55\x4C\x54\x20", 8); 


bitmapl = default_bitmap; 
bitmap2 = default2_bitmap; 
[eesteecnersesesseesesae cease seseeseseesasessoeeeasce */ 
/* Copy role header */ 
/Rassseessesossessesscesenscsesstocsseesesesscesseses */ 


memcpy (work_ptr, (void*)&role_ header, sizeof(role_header)); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(role header) ; 


[Reeeeeseessssatoecsas ee eaeSeseesssoseesaesesesceenee */ 
/* Copy access control points header */ 
[ReccaSeeeceseeseseseoe eee eseee ease ese eese ee eS */ 


memcpy (work_ptr, 
(void *)&access_control_points_header, 
sizeof(access control _points_ header) ); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access control _points_header) ; 


[#eeeseeasenesessessas son ae cstessaseceesaeseoaeesasse */ 
/* Copy access control points segment 1 */ 
/Reeescessssessessesecteeusesesscseseeesessescosseads */ 
access_control_points_segment_header.start_bit = 0; 

access_control_points_segment_header.end_bit = 0x127; 


access_control_points_segment_header.number_bytes = 
sizeof (default_bitmap) ; 
memcpy (work_ptr, 
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(void *)&access control_points_segment_header, 
sizeof (access _control_points_segment_header)); 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access control_points_segment_header) ; 


| Hose cecesdeesces sess eneeeesstasecesene sass seeeseecesS */ 
/* Copy access control points segment 1 bitmap */ 
[eeehseaesecs ea sane ses se eee soe ae] eaeer => sas eee aeeas */ 


memcpy(work_ptr, bitmapl, sizeof (default_bitmap)); 


/* Adjust work pointer to 
point after bitmap. */ 
work_ptr += sizeof (default_bitmap) ; 


[xXScessesesseaoanss soeneae ase sseaaasasssasessescosaas */ 
/* Copy access control points segment 2 */ 
/esecssousssessosensssscssesseescetesesessctscasseccs */ 
access_control_points_segment_header.start_bit = 0x200; 
access_control_points_segment_header.end_bit = O0x23F; 


access_control_points_segment_header.number_bytes = 
sizeof (default2_bitmap) ; 


memcpy (work_ptr, 
(void *)&access control_points_segment_header, 
sizeof (access _control_points_segment_header)) ; 


/* Adjust work pointer to 
point after header. */ 
work_ptr += sizeof(access_control_points_segment_header) ; 


[fseurenes=aeaasesesaeeeeee see sss eaaas=eseasaesseeea= */ 
/* Copy access control points segment 2 bitmap */ 
| ee eee ae eee */ 


memcpy(work_ptr, bitmap2, sizeof (default2_bitmap)); 


rule_array_count = 2; 

memcpy(rule_array, "“INIT-AC REPLACE ", 16); 

verb_datal_length = 0; 

verb_data2_length = sizeof(aggregate_role header) + 
sizeof(role header) + 
sizeof(access control points header) + 
sizeof(access_control_points_segment_header) 
x2 + 
sizeof(default_bitmap) + 
sizeof (default2_bitmap) ; 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
(long *) &verb_datal_length, 
(char *) verb_datal, 
(long *) &verb_data2_length, 
(char *) verb_data2); 


if (return_code > 4) 
printf("The default role was not replaced. Return/reason code: \ 
%d/%d\n",return_code, reason_code); 
else 
printf("The default role was successfully updated.\n"); 
} 
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Example: ILE RPG program for creating roles or profiles for your 4758 


Coprocessor 


Change this program example to suit your needs for creating roles and profiles for your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRAKKAKKK KKK KKK KEK KKK ERK KKK KKK KER KKK ERK KEKE RRR KK RR RRR KERR RK 
D* CRTROLEPRF 

Dx« 

D* Sample program to create 3 roles and 3 profiles in the 4758 
D* and change the authority for the default role. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(CRTROLEPRF) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CRTROLEPRF) SRCFILE(SAMPLE) 
D* CRTPGM PGM(CRTROLEPRF) MODULE (CRTROLEPRF) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUAACI service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
Dx Access Control_Initialize (CSUAACI) 


Dx« 

DA KRAK KKK KKK KEK KKK ERK KK ERK KEK KERR KER KER RRR KER KR ERK RR RRR ERR KERR ERER 
Dee eee ee 
D* Declare variables used by CCA SAPI calls 
Pxeeeseaseeseeeseceses es selec e sees e see eee eee esse eee eae 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN 5 9B 0 

Dx xx Exit data 

DEXITDATA 5 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Text length 

DTEXTLEN S 9B 0 

Dx ** Text to hash 

DTEXT S 20 

D* ** Chaining vector length 
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DCHAINVCTLEN S 9B 0 INZ(128) 


Dx ** Chaining vector 

DCHAINVCT S 128 

Dx ** Hash length 

DHASHLEN S 9B @ INZ(20) 

P¥eeeeeee ees sccceeeesceee cece sees cee ce ee cess ccess esse sce sce es 


D* VERBDATA1 contains the aggregate profile structure which 
D* in turn contains 3 profiles. 


Px¥eceeSScSsosscseccssso ses stess ccs sseSss cscs seca ssessceesees 
DVERBDATALEN1 S 9B 0 INZ(278) 
DVERBDATA1 DS 278 

Dx ** Define 3 Profiles 

DNUMPROFS 9B 0 INZ(3) 

Dx ** Reserved field 

DRESR1 9B © INZ(Q) 
DPROF1 90 

DPROF2 90 

DPROF3 90 

Dx« 

DxkteeSe eae Sse sSae sf Sse Sena aS aaa e Sea ass Sao ae = = = = Se 
D* Define the profile structure 

Dksse sees e ee cats sees tee ese ee sees es eh eee sees seen cee sesss 
DPROFILESTRUCT DS 

Dx ** Version 1 struct 

DPROFVERS 2 INZ(X'0100') 
Dx ** Length of profile 

DPROFLEN 2 INZ(X'005A') 
Dx *x Description of profile 
DCOMMENTP 20 INZ(' 

Dx ** Checksum is not used 
DCHECKSUMP 2 INZ(X'0000') 
Dx ** Logon failure count 

DLOGFC 1 INZ(X'00') 
Dx ** Reserved 

DRESR2 1 INZ(X'00') 
Dx ** Profile name 

DUSERID 8 

Dx ** Role used 

DROLENAME 8 

Dx xx Activation year (2000) 
DACTYEAR 2 INZ(X'07D0') 
Dx xx Activation month (01) 
DACTMONTH 1 INZ(X'Q1') 
Dx xx Activation day (01) 

DACTDAY 1 INZ(X'01') 
Dx xx Expiration year (2004) 
DEXPYEAR 2 INZ(X'07D4') 
Dx *x* Expiration month (12) 
DEXPMONTH 1 INZ(X'OC') 
Dx xx Expiration day (31) 

DEXPDAY 1 INZ(X'1F') 
D« ** Total authentication 

Dx ** data length 

DTOTAUTDTALEN 2 INZ(X'0024') 
Dx ** Field type 

DFIELDTYPE 2 INZ(X'0001') 
D« ** Authentication data len 
DAUTDATLEN 2 INZ(X'0020') 
Dx ** Authentication mechanism 
DMECHANISM 2 INZ(X'0001') 
Dx ** Mechanism strength 

DSTRENGTH 2 INZ(X'0000') 
Dx ** Mech expiration year (2004) 
DMCHEXPYEAR 2 INZ(X'07D4') 
Dx ** Mech expiration month (12) 
DMCHEXPMONTH 1 INZ(X'OC') 
Dx *x* Mech expiration day (31) 
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DMCHEXPDAY 
Dx 
DATTRIBUTES 
Dx« 
DAUTHDATA 
Dx« 


** 


** 


1 INZ(X'1F') 
Attributes 
4 INZ(X'80000000' ) 
Authentication data 
20 INZ(' 


D* The Default role is being replaced 


D* Verb_data_2 length set to the length of the default role 


D* VERBDATA2 contains the aggregate role structure which 
D* in turn contains 3 roles. 


DVERBDATA2 
Dx« 
DNUMROLES 
Dx 

DRESR3 
DROLE1 
DROLE2 
DROLE3 

Dx 


DROLESTRUCT 
Dx« 
DROLEVERS 
Dx 
DROLELEN 
Dx« 
DCOMMENTR 
Dx« 
DCHECKSUMR 
Dx« 

DRESR4 

Dx« 

DROLE 

Dx 
DAUTHSTRN 
Dx« 
DLWRTIMHR 
DLWRTIMMN 
Dx« 
DUPRTIMHR 
DUPRT IMMN 
Dx« 
DVALIDDOW 
Dx 

DRESR5 

Dx 
DNUMSEG 
Dx« 

DRESR6 

Dx« 
DSTART1 
Dx 

DEND1 

Dx« 
DNUMBYTES1 
Dx 

DRESR7 

Dx« 
DBITMAP1A 
DBITMAP1B 


DS 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


Define 3 Roles 
9B @ INZ(3) 

Reserved field 
9B © INZ(O) 

109 


Version 1 struct 
2 INZ(X'0100') 
Length of role 
2 INZ(X'006D') 
Description of role 
20 INZ(' 
Checksum is not used 
2 INZ(X'0000') 
Reserved field 
2 INZ(X'0000') 
Role Name 
8 
Authentication strength is set to 0 
2 INZ(X'0000') 
Lower time is 00:00 
1 INZ(X'00') 
0') 


1 INZ(X'00' 
Upper time is 23:59 

1 INZ(X'17') 

1 INZ(X'3B') 


Valid days of week 

1 INZ(X'FE') 
Reserved field 

1 INZ(X'Q0') 


2 Access control points segments are defined 


2‘ INZ(X'0002') 
Reserved field 

2 INZ(X'0000') 
Starting bit of segment 1 is 0 

2 INZ(X'0000') 


Ending bit of segment 1 is 295 (Hex 127). 


2 INZ(X'0127') 
37 Bytes in segment 1 

2 INZ(X'0025') 
Reserved field 

2 INZ(X'00') 
Segment 1 access control pointer 

8 

8 
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DBITMAP1C 8 

DBITMAP1D 8 

DBITMAP1E 5 

Dx ** Starting bit of segment 2 is 512 (Hex 200) 
DSTART2 2 INZ(X'0200') 

Dx *x* Ending bit of segment 2 is 575 (Hex 23F) 
DEND2 2 INZ(X'023F') 

D* ** 8 Bytes in segment 2 

DNUMBYTES2 2 INZ(X'0008') 

Dx ** Reserved field 

DRESR8 2 INZ(X'0000') 

Dx ** Segment 2 access control points 

DBITMAP2 8 

Dx 

Dx« ia niacee eae a ea ae eee a aa—S eae SaaS * 

Dx * DEFAULT expressed in ASCII * 

Dx I si i esa ci * 

DDEFAULT S 8 INZ(X'44454641554C5420') 
Dx« 


DA KRAKKKKK KK KER KKK EK KKK ERK KKK ERK KEKE RK KERR KKK KER KEKE RKR KEKE 


D* Prototype for Access Control Initialize (CSUAACI) 


DA KRKKKKKK KKK ERK KKK KKK KERR KKK KERR KERR RRR R KK RR ER KERR ERK KR EERE 


DCSUAACI PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DRARRAYCT 9B 0 
DRARRAY 16 
DVRBDTALEN1 9B 0 
DVRBDTA1 278 
DVRBDTALEN2 9B 0 
DVRBDTA2 335 

Dx« 


DAKAR KKKKKKK KER KKK KKK KEKE RK KERR RRR ERR RRR ERK KR ER KERR ERK KR RERRERK 


D* Prototype for One_Way_Hash (CSNBOWH) 


DAKAR KKKKK KKK ERK KEKE KKK KERR KER ERK RRR ERR RRR RRR KERR ERK KER ERREEK 


DCSNBOWH PR 

DRETCOD 9B 0 

DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DTXTLEN 9B 0 

DTXT 20 

DCHNVCTLEN 9B 0 

DCHNVCT 128 

DHSHLEN 9B 0 

DHSH 20 

Dx« 

[De ee eee ee 
Dx ** Declares for sending messages to the 
Dx ** job log using the QMHSNDPM API 

D¥eebeee eee ee ste Se ee es eee eee ese Secs eee eee see e eee eeeea = 
DMSG S 64 DIM(3) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(64) 

D DS 

DMSGTEXT 1 75 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
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DSTACKCOUNTER S 9B 0 INZ(2) 


DERRCODE DS 

DBYTESIN 1 4B © INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx 

CK KKK KKK EK KKK KKK KR EK EK KEK ERK KK EKER KKK EK KERR ERE RK RR ERE REE ERR ERE 
Cx START OF PROGRAM * 
Cx* * 
CkeesScceeseesssecescesss os acsinsecsseescssessessscsees soseissce * 
Cx Set up roles in verb data 2 * 
Cksescceceschissseccectecleesosscee soc Ssecosescoseseesassesssece * 
Cx Set ROLE name (ROLE1) 

C MOVEL 'ROLEL =! ROLE 

Gx) “KSeseesesscescuscussccosesscseseess esse sscessessss sSesses 
Cx * Set Access Control Points for ROLE1 

Cx * 

C* »* DEFAULT is authorized to all access control points 

Cx * except for the following: 

Cx * 0x0018 - Load 1st part of Master Key 

Cx * 0x0019 - Combine Master Key Parts 

Cx * Ox001A - Set Master Key 

Cx * 0x0020 - Generate Random Master Key 

Cx * 0x0032 - Clear New Master Key Register 

Cx * 0x0033 - Clear Old Master Key Register 

Cx * Ox@0D6 - Translate CV 

Cx * 0x0110 - Set Clock 

Cx * Ox@111 - Reinitialize device 

Cx * 0x0112 - Initialize access control system 

Cx * 0x@113 - Change user profile expiration date 

Cx * 0x0114 - Change authentication data (eg. passphrase) 
Cx * 0x@115 - Reset password failure count 

Cx * 0x@116 - Read Public Access Control Information 

Cx * 0x@117 - Delete user profile 

Cx * 0x@118 - Delete role 

Cx * 0x@119 - Load Function Control Vector 

Cx * Ox@11A - Clear Function Control Vector 

Cx * 0x@11B - Force User Logoff 

Cx x 0x@200 - Register PKA Public Key Hash 

Cx * 0x0201 - Register PKA Public Key, with cloning 

Cx * Ox0202 - Register PKA Public Key 

Cx * 0x0203 - Delete Retained Key 

Cx * 0x0204 - PKA Clone Key Generate 

Cx x 0x@211 - Ox21F - Clone information - obtain 1-15 

Cx x 0x@221 - Ox22F - Clone information - install 1-15 

Cx * 

Cx »* ROLE 1 is authorized to all access control points 

Cx * to which the DEFAULT role is authorized plus the following: 
Cx «* 

Cx * @x0018 - Load 1st part of Master Key 

Cx * @x0020 - Generate Random Master Key 

Cx * Qx0Q32 - Clear New Master Key Register 

Cx * Q@x0@53 - Load lst part of PKA Master Key 

Cx * @x0Q60 - Clear New PKA Master Key Register 

C* *  @x0119 - Load Function Control Vector 

Cx * @x0201 - Register PKA Public Key, with cloning 

Cx * @x0202 - Register PKA Public Key 

Cx * @x0203 - Delete Retained Key 

Cx *  @x0@204 - PKA Clone Key Generate 

Cx * @Qx0211 - 0x215 - Clone information - obtain 1-5 

Cx * Qx0221 - 0x225 - Clone information - install 1-5 

Cx * 

(a eee 

C EVAL BITMAP1A = X'Q003F09D80002000' 

C EVAL BITMAP1B = X'8000100080000000' 

C EVAL BITMAP1C = X'Q00A8000881F7110' 

C EVAL BITMAP1D = X'1004031180000000' 

C EVAL BITMAP1E = X'FF7FOQ4F80' 
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C EVAL BITMAP2 = X'78007CO07COQOE60F' 
Cx Copy role into aggregate structure 

C MOVEL ROLESTRUCT ROLE1 

Cx Set ROLE name (ROLE2) 

C MOVEL "ROLE2 . ROLE 

Gk “KeSesocescecscceesesscsccsseseSes cs Sacecseseosasssssecescs 


Cx »* Set Access Control Points for ROLE2 


Cx * 

Cx »* ROLE 2 is authorized to all access control points 
Cx »* to which the DEFAULT role is authorized plus the following: 
Cx «* 

Cx *  @x0019 - Combine Master Key Parts 

Cx * @xOQ01A - Set Master Key 

Cx * Qx0033 - Clear Old Master Key Register 

Cx *  @x0054 - Combine PKA Master Key Parts 

Cx *  @x0057 - Set PKA Master Key 

Cx »* Qx0061 - Clear Old Master Key Register 

Cx »* Qx011A - Clear Function Control Vector 

Cx * Qx0200 - Register PKA Public Key Hash 

Cx * @x0201 - Register PKA Public Key, with cloning 

Cx * @x0203 - Delete Retained Key 

Cx *  @x0@204 - PKA Clone Key Generate 

Cx * Qx0216 - 0x21A - Clone information - obtain 6-10 

Cx * Qx0226 - Ox22A - Clone information - install 6-10 
Cx «* 

Ck -#Sssheteecsictee eee ssesee see eee ce eee eee eee eee eee ce 
C EVAL BITMAP1A = X'0Q03F07D80001000' 
C EVAL BITMAP1B = X'8000090040000000' 
C EVAL BITMAPIC = X'Q00A8000881F7110' 
C EVAL BITMAP1D = X'1004031180000000' 
C EVAL BITMAP1E = X'FF7FOQ2F80' 

C EVAL BITMAP2 = X'D80003E003E0E60F' 
Cx Copy role into aggregate structure 

C MOVEL ROLESTRUCT ROLE2 

Cx Set ROLE name (ROLE3) 

¢ MOVEL 'ROLE3 ROLE 

Ck “KesSssceoaseeacecesseesecase esses ecies se cee ecm ec eee cesses 
Cx »* Set Access Control Points for ROLE3 

Cx «* 

Cx »* ROLE 3 is authorized to all access control points 
C* »* to which the DEFAULT role is authorized plus the following: 
Cx «* 

Cx * @x0110 - Set Clock 

Cx »* Q@x0111 - Reinitialize device 

Cx * @x0112 - Initialize access control system 

Cx »* @x0113 - Change user profile expiration date 

C* * @x0114 - Change authentication data (eg. passphrase) 
Cx »* @x0115 - Reset password failure count 

C* »* @x0116 - Read Public Access Control Information 

C* »* @x0117 - Delete user profile 

Cx * @x0118 - Delete role 

Cx *  @x@11B - Force User Logoff 

Cx * @x0200 - Register PKA Public Key Hash 

Cx * Qx0201 - Register PKA Public Key, with cloning 

Cx * @x0203 - Delete Retained Key 

Cx *  @x0204 - PKA Clone Key Generate 

Cx * @x021B - 0x21F - Clone information - obtain 11-15 
Cx * Qx022B - Ox22F - Clone information - install 11-15 
Cx * 

Ge. “Kesesescaseatesoseoe st est esee eee essere sees eee e eee eee 
C EVAL BITMAP1A = X'0Q03F01D00000000' 
C EVAL BITMAP1B = X'8Q000000C0000000' 
C EVAL BITMAPIC = X'Q00A8000881F7110' 
C EVAL BITMAP1D = X'1004021180000000' 
C EVAL BITMAP1E = X'FF7FFF9F8Q' 

C EVAL BITMAP2 = X'D800001F001FE60F' 
Cx Copy role into aggregate structure 
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C MOVEL ROLESTRUCT ROLE3 


Cxkee ete eee sees scat s ce sce escce ea cee se eee ese eee ose Sass esa eee ee * 

Cx Set up roles in verb data 1 * 

CXer eevee seseees ese sees ese ee ate eee ee ee tee eee ss ee ceeeeeeees * 

Cx Set Profile name (SECOFR1) 

C MOVEL "SECOFR1 ' USERID 

Cx Set Role name (ROLE1) 

C MOVEL 'ROLEL =! ROLENAME 

Cx Hash pass-phrase for profile 1 

C SETOFF 05 
EVAL TEXT = 'Is it safe' 
Z-ADD 10 TEXTLEN 
EXSR HASHMSG 

05 SETON LR 


~ 


Copy profile into aggregate structure 
MOVEL PROFILESTRUCT PROF1 
Set Profile name (SECOFR2) 


+ 


MOVEL "SECOFR2 ' USERID 

* Set Role name (ROLEZ) 
MOVEL "ROLE2 ~~ s' ROLENAME 

* Hash pass-phrase for profile 2 
EVAL TEXT = 'I think it is safe' 
Z-ADD 18 TEXTLEN 
EXSR HASHMSG 

05 SETON LR 


+ 


Copy profile into aggregate structure 
MOVEL PROFILESTRUCT PROF2 
Set Profile name (SECOFR3) 


~ 


AOAOAADOAO0 8 OF O30IG3OO3F OQ OOO: 


MOVEL "SECOFR2 ' USERID 
* Set Role name (ROLE3) 

MOVEL "ROLE3 ROLENAME 
* Hash pass-phrase for profile 3 

EVAL TEXT = 'Is what safe' 

Z-ADD 12 TEXTLEN 

EXSR HASHMSG 

05 SETON LR 

* Copy profile into aggregate structure 

MOVEL PROFILESTRUCT PROF3 
CxksesSeseeslassce lessee ssessesseeccsossessessceseesees sss escecc * 
Cx Set the keywords in the rule array * 
CkHsSeed cece eee eee ee ce sete sce e eee eee ease eee tse ce see eee * 
C MOVEL "INIT-AC ' RULEARRAY 
C MOVE "REPLACE ' RULEARRAY 
C Z-ADD 2 RULEARRAYCNT 


CR KKK KK KKK KKK KEKE KR EKER KEK ERE KK EKER KR KERR ER EKER RR EKER KERR ERR ERE 


C* Call Access Control_Initialize SAPI 


CK KKK RK EK KKK KKK KR KEKE KK KEK ERK KK EKER KKK RK ERE RK ER ERE RK ERR ERE 


C CALLP CSUAACI (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

¢ VERBDATALEN1: 
C VERBDATAI: 

C VERBDATALEN2: 
C VERBDATAZ) 

Cx« $oscvsessecssasssssescoses * 

Cx »* Check the return code * 

Cx* Pome eeseeseenecseseecees * 

C RETURNCODE IFGT 0 

Cx Ressossssccsccssssesssscu * 

Cx * Send failure message * 

Cx* Renee eeeeceseeeececeeesee * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 
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C MOVEL "CSUAACI' SAPI 

C EXSR SNDMSG 

C RETURN 

C ELSE 

Cx« tiene cesaeeseesteseesoses * 

Cx * Send success message * 

Cx* Posse cae soa ea ee ome tee * 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

C ENDIF 

Cx 

CkeetiseSe sce sete ee se reeeee es ecee esas see ste ese eeese see ecessess * 
Cx Change the Default Role * 
ee ee eee eee ee eee eee ee * 
Cx Set the Role name 

C MOVEL DEFAULT ROLE 

Gk: Hessc sce see ceeereceieesc oases seen scseSeecteeceec kee ces see 
Cx »* Set Access Control Points for DEFAULT 

Cx «* 

(Ce aaah -S2-e2so-eeSsease sas Soa esa eee Sec ee eee sae seee eae 
C EVAL BITMAP1A = X'0Q03F01D00000000' 
C EVAL BITMAP1B = X'8Q00000000000000' 
C EVAL BITMAP1C = X'0Q0A8000881F7110' 
C EVAL BITMAP1D = X'1004021180000000' 
C EVAL BITMAP1E = X'FF7F406B80' 

C EVAL BITMAP2 = X'OQODDQ0DQ000Q0E6OF ' 
Cx Copy role into aggregate structure 

C MOVEL ROLESTRUCT ROLE1 

Cx« 

Cx Set the new verb data 2 length 

C Z-ADD 117 VERBDATALEN2 

Cx 

C* Set the verb data 1 length to @ (No profiles) 

C Z-ADD 0 VERBDATALEN1 

Cx Change the number of roles to 1 

C Z-ADD 1 NUMROLES 

C 


CK KKK KKK KKK KK KKK KR KK ERK EK EKER KEK ER KERR RK KERR ERE RE RR ERE RE RK ERR ERE 


Cx Call Access Control_Initialize SAPI 


CR K KK KKK KKK KK EK KERR EKER KEK ERE RK RK EKER KEKE RR ER ERE RR ERE REE ERR ERE 


¢ CALLP CSUAACTI (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C VERBDATALEN1: 
C VERBDATAI: 

C VERBDATALEN2: 
C VERBDATAZ) 
CekSeetstseseesc cesses oe eee * 

Cx Check the return code * 

CxeSoSecsesasseeseose=eee= * 

C RETURNCODE IFGT 0 

Cx Keane micas aii ee am iam eae * 

Cx * Send failure message * 

Cx« teceeoseceseeseesecssocac * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSUAACI' SAPI 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx* foenso cee eee mee wee * 

Cx * Send success message * 

Cx« toSessaasascusSssecsocoae * 
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C MOVEL MSG (3) MSGTEXT 


C EXSR SNDMSG 
Cx 

C ENDIF 

Cx« 

C SETON 

Cx* 


CRRA KKK KKK KKK KKK KR EKER KER ERK KK EKER KKK EKER EKER ERR ERE RK EKER 


Cx Subroutine to send a message 
CR KKK KK KKK KKK KEKE KR ERE KK EK ERK KK EKER KKK RK KKK EKER KERR ER ERK RK ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


CK KKK KKK KKK KK KKK KKK KEK KEK ERK KK EKER KKK RK KERR ER ERK RR ER ERE ERR ERE 


Cx Subroutine to Hash pass-phrase 
CR KKK KKK KEK KKK KKK KR EKER KER ERK KK EKER KKK EKER EKER KERR ERE REE ERR ERE 


C HASHMSG BEGSR 

Cx« Pesos sessessoessssscaseasseoseosesocasoseaas * 

Cx »* Set the keywords in the rule array * 

Cx« Pe seeesessssecessessscsscse see see se ssc soese * 

C MOVEL "SHA-1 : RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
Cx« ssc Ssesessceessssecseessa * 

Cx »* Call One Way Hash SAPI * 

Cx* Cicnis ves canoe tao meen ees * 

C CALLP CSNBOWH (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT : 
C RULEARRAY : 
C TEXTLEN: 

C TEXT: 

C CHAINVCTLEN: 
C CHAINVCT: 

C HASHLEN: 

C AUTHDATA) 
Ck tk#eSSsesscesosocssossSacaes * 

Cx »* Check the return code * 

CX #evsccceceeasesseseeasee * 

C RETURNCODE IFGT 0 

Cx* Psatakeascancanaseaca sais * 

Cx * Send failure message * 

C* Pelee ete a eit eet ee lee * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNBOWH' SAPI 

C EXSR SNDMSG 

C SETON 

C ENDIF 

Cx« 

C ENDSR 


** 

CSUAACI failed with return/reason codes 9999/9999. 

SECOFR1, SECOFR2, and SECOFR3 profiles were successfully created. 
The Default role was successfully changed. 


LR 


05 
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Example: ILE C program for enabling all access control points in the default role 
for your 4758 Coprocessor 

Change this program example to suit your needs for enabling all access control points in the default role 
for your 4758 Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


feassccectese casesessoasussescssasssesessssaseesses sessescesceesecess «/ 
/* SETDEFAULT */ 
/* x/ 
/* Sample program to authorize the default role to all access x/ 
/* control points in the 4758. x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 x/ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(SETDEFAULT) x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* CRTCMOD MODULE(SETDEFAULT) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(SETDEFAULT) MODULE(SETDEFAULT) x/ 
/* BNDSRVPGM(QCCA/CSUAACI) x/ 
/* x/ 
/* Note: Authority to the CSUAACI service programs x/ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Access Control_Initialization (CSUAACI). x/ 
/* x/ 
/* Note: This program assumes the device you want to use is x/ 
/* already identified either by defaulting to the CRPO1 x/ 
/* device or has been explicitly named using the x/ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
[Rese sSSess eas see sesteasensesasseeeSeassseaseeeshee noses seceseens sees «/ 
#include "csucincl.h" /* header file for CCA Cryptographic 

Service Provider for iSeries */ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


void main(int argc, char *argv[]) { 


/* standard return codes */ 
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#define ERROR -1 
#define OK 0 
#define WARNING 4 


long return_code; 

long reason_code; 

long exit_data_length; 
char exit_data[2]; 

char rule_array[4] [8]; 
long rule_array_count; 
long verb_datal_length; 
long verb_data2_length; 
char verb_datal[4]; 


| ee eee eee ee */ 
/* Structure for defining a role */ 
| Reeeeecera sees s=sceee reer =ens es ease - esses eae aaa a ae ae oe ee */ 
struct role_header 

{ 

char version[2]; 

short length; 

char comment [20] ; 

short checksum; 

short reserved1; 

char role[8]; 

short auth_strength; 

char lower_time_hour; 

char lower_time_minute; 

char upper_time_hour; 

char upper_time_minute; 

char valid_days_of_week; 

char reserved2; 

} role_header; 
| a ee ee ee */ 
/* Structure for defining aggregate roles x/ 
| eee ee ee ee eee ee eee ee ee eee */ 
struct aggregate_role 

long number; 

long reserved; 


} aggregate_role_header; 


[Resse Sere eee See eee sheet ee seer eeeeH eee ee aoe eens ees e cee ese */ 
/* Structures for defining the access control points in a role */ 
{Reet eecedesesess eet sas ness see a= See esas ese eee eae ae oe ease */ 


struct access_control_points_ header 
{ 
short number_segments; /* Number of segments of */ 
/* the access points map */ 
short reserved; 
} access_control_points header; 


struct access _control_points_segment_header 


{ 
short start_bit; /* Starting bit in this */ 
/* segment. */ 
short end_bit; /* Ending bit */ 
short number_bytes; /* Number of bytes in */ 
/* this segment x/ 
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/* 
/* 
/* 
/* 


ch 


ch 
U 
U 


i 


V 


short reserved; 
} access_control_points_segment_header; 


Default role - access control points list - 
authorized to everything 


For access control points 0x01 - Qx127 
ar default_bitmap[] = 
{ 0x00, 0x03, OxFO, OxFD, 0x80, 0x00, 0x30, 0x00, 
0x80, 0x00, 0x19, 0x00, OxCO, Ox00, Ox00, 0x00, 
0x00, Ox0A, 0x80, Ox00, 0x88, Ox2F, Ox71, 0x10, 
0x18, 0x04, 0x03, 0x31, Ox80, Ox00, Ox00, 0x00, 
OxFF, Ox7F, OxFF, OxFF, 0x80}; 


ar default2_bitmap[] = 
{ OxF8, 0x00, Ox7F, OxFF, Ox7F, OxFF, OxE6, OxOF }; 


nsigned char * verb _data2; 

nsigned char * work_ptr; 

nt i; /* Loop counter */ 
PeeeeseesuecueSeseseescnp Hees sSaeaas nec ee cer eRaeRetRaensossoneee */ 
* Start of code x/ 
Se ee ee ee ee ee ee ae ee ee ee a */ 
Pose ccee een nce eee ae eee ace neteeeenene wen Gonche se */ 
* Allocate storage for the aggregate role structure x/ 
ee ee ee ee ee a ae */ 


erb_data2 = malloc(sizeof(aggregate_role header) + 
sizeof(role_ header) + 
sizeof(access control points _header) + 
sizeof(access_control_points_segment_header) 
* 2 + 
sizeof(default_bitmap) + 
sizeof (default2_bitmap)); 


work_ptr = verb_data2; /* Set up work pointer */ 


aggregate_role_header.number = 
aggregate_role_header.reserved 


1; /* Define/replace 1 role */ 
= 0; /* Initialize reserved fieldx/ 


/* Copy header to verb data2 
storage. x/ 


memcpy (work_ptr, (void*) &aggregate_role_header, 


sizeof (aggregate _role header) ); 


work_ptr += sizeof(aggregate_role header); /* Set work pointer 


after role header */ 


[Raenciaasmaaee sasaeeses sesso see sees sees es aos sees ee osee-=--5-45= */ 
/* Fill in the fields of the role definition. */ 
| eee ee eee oe ee eee ee ee ee eee ee eee ee eee */ 
role_header.version[0] = 1; /* Version 1 role */ 
role_header.version[1] = 0; 


/* Set length of the role */ 


role_header.length =  sizeof(role_header) 


+ sizeof(access_control_points_header) 

+2 

sizeof (access_control_points_segment_header) 
+ sizeof (default_bitmap) 

+ sizeof (default2_bitmap) ; 
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role_header.checksum = 0; /* Checksum is not used x/ 

role_header.reserved1 = 03 /* Reserved must be 0 x/ 

role_header.auth_strength = 0; /* Authentication strength */ 
/* is set to 0. */ 
/* Lower time is 00:00 */ 

role_header.]ower_time_hour = 0; 

role_header.lower_time_minute = 0; 
/* Upper time is 23:59 */ 

role_header.upper_time_hour = 235 

role_header.upper_time_minute = 59; 

role_header.valid_days_of_week = OxFE; /* Valid every day */ 
/* 7 bits - 1 bit each day */ 

role_header.reserved2 = 0; /* Reserved must be 0 */ 
/* Role is DEFAULT */ 
/* expressed in ASCII x*/ 


memcpy(role_header.role, "\x44\x45\x46\x41\x55\x4C\x54\x20", 8); 


memset (role_header.comment,' ',20); /* No description for role */ 


[Rasa aeeesoseree see ceaeeeeseas oss <Se seers ecesecssces= */ 
/* Copy role header into verb_data2 storage */ 
[#esesse ase seen sssslossenscsseonsesseeseeeeenneece se */ 


memcpy (work_ptr, (void*)&role_ header, sizeof(role_header)) ; 
work_ptr += sizeof(role_header) ; 


| ee eee ere */ 
/* Set up access control points header and then */ 
/* copy it into verb_data2 storage. */ 
/sesescesbaseessssssecesceessesssssssesoeessssassece */ 
access_control_points_header.number_segments Eines 
access_control_points_header.reserved = 0; 
access_control_points_segment_header.reserved = 0; 


memcpy (work_ptr, 
(void *)&access_control_points header, 
sizeof (access control_points_header)); 


/* Adjust work_ptr to point to the 
first segment x/ 
work_ptr += sizeof(access control _points_header) ; 


/#esesssssasesscssesecusenscsesccsceeeeseescscesscse= */ 
/* Set up the segment header for segment 1 and then */ 
/* copy into verb_data2 storage */ 
| a ee eee eee ee eee */ 
access_control_points_segment_header.start_bit = 0; 

access_control_points_segment_header.end_bit = 0x127; 


access_control_points_segment_header.number_bytes = 
sizeof (default_bitmap) ; 
memcpy (work_ptr, 
(void *)&access_control_points_segment_header, 
sizeof(access_control_points_segment_header) ); 


/* Adjust work_ptr to point to the 
first segment bitmap */ 
work_ptr += sizeof(access_control_points_segment_header) ; 


[dosmeeeasesosensssSbaseeetaeseseeeeseseaceeseeeeee eS */ 
/* Copy access control points segment 1 bitmap */ 
[ese tevnehseseneessceascassaseneseeccasenaseese=s55 */ 


memcpy(work_ptr, default_bitmap, sizeof (default_bitmap)); 
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/* Adjust work_ptr to point to the 
second segment */ 
work_ptr += sizeof (default_bitmap) ; 


[sean ca cseee aos ae asee sees sae cea eee esas aos aeoeeeeee */ 
/* Set up the segment header for segment 2 and then */ 
/* copy into verb_data2 storage */ 
| Hee sesessies Sees e seas ee eseseseeeseeeSssoseeeseeeese */ 
access_control_points_segment_header.start_bit = 0x200; 
access_control_points_segment_header.end_bit = Ox23F; 


access_control_points_segment_header.number_bytes = 
sizeof (default2_bitmap) ; 


memcpy (work_ptr, 
(void *)&access_control_points_segment_header, 
sizeof(access_control_points_segment_header) ); 


/* Adjust work_ptr to point to the 
second segment bitmap x/ 
work_ptr += sizeof(access_control_points_segment_header) ; 


[xeecnbesesesessees sedans eer acon asececseeseeeecseisS */ 
/* Copy access control points segment 2 bitmap */ 
/esacsdcusssecssseccsseesesssesscssestesscassecasceses */ 
memcpy(work_ptr, default2_bitmap, sizeof (default2_bitmap)); 
[Seecseceecasasscasaceseneseee aera cee sesesesseceneea */ 
/* Set the length of verb data 2 (Role definition) */ 
/ eeacsascwsasasssesnseesessesseesseeesessssosscessencs */ 


verb_data2_length = sizeof(aggregate_role header) + 
role_header. length; 


j Reece aaees=ee=as <-Sseeseeee see ss=essessesaa5-—-seeens */ 
/* Set remaining parameters x/ 
[xeeee Sees esseese seats sesesee ee erases ene aeseee ts ecceS */ 


rule_array_count = 2; 
memcpy(rule_array, “INIT-AC REPLACE ", 16); 
verb_datal_length = 0; 


| ee eee ee eee x/ 
/* Call Access Control Initialize (CSUAACI) to set the */ 
/* default role. */ 
[Reeaaeeee See eesersseesescesetasee sees=as =aSacseeeseese= x/ 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char *)rule_array, 
&verb_datal_length, 
(unsigned char *) verb _datal, 
&verb_data2_length, 
verb_data2) ; 


if (return_code > 4) 
printf("The default role was not replaced. Return/reason code: \ 
%d/%d\n",return_code, reason_code); 
else 
printf("The default role was successfully updated.\n"); 
} 


Example: ILE RPG program for enabling all access control points in the default 
role for your 4758 Coprocessor 

Change this program example to suit your needs for enabling all access control points in the default role 
for your 4758 Coprocessor. 
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Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRAKKKKK KKK KK KKK EK KKK KR KKK KKK KK ER KKK RRR KK RRR RK RRR KR EER KERR 
D* SETDEFAULT 

Dx« 

D* Sample program to authorize the default role to all access 

D* control points in the 4758. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


D* these programs and files. 


Dx 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(SETDEFAULT) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(SETDEFAULT) SRCFILE(SAMPLE) 
D* CRTPGM PGM(SETEID) MODULE(SETDEFAULT) 


Dx BNDSRVPGM(QCCA/CSUAACI) 

Dx 

D* Note: Authority to the CSUAACI service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
Dx Access _Control_Initialize (CSUAACI) 
Dx 


DA KRKKK KKK KK KEK KK KERR KK ERK RRR KERR KERR RRR RRR KR ERR RRR KEKE RE RRRERRRER 


DxeeeSaesesscesesoaaaasssssaasseaseeSeee sae - sea ee—-25=-s5—-= 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN 5 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT 5 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Verb data 1 length 

DVERBDATALEN1 S 9B 0 INZ(0) 

Dx ** Verb data 1 

DVERBDATA1 S 4 

Dx ** Verb data 2 length 

DVERBDATALEN2 > 9B © INZ(117) 

Pee Scecossesselecescee esl Ssesesces sess ssc secseSssoSseseoseeee 


D* Verbdata 2 contains the aggregate role structure which 
D* in turn contains 1 role - the default role 
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DVERBDATA2 
Dx 
DNUMROLES 
Dx« 

DRESR1 

Dx 

DVERS 

Dx 
DROLELEN 
Dx« 
DCOMMENT 
Dx 
DCHECKSUM 
Dx« 

DRESR2 

Dx« 

DROLE 

Dx« 
DAUTHSTRN 
Dx« 
DLWRTIMHR 
DLWRTIMMN 
Dx 
DUPRTIMHR 
DUPRTIMMN 
Dx« 
DVALIDDOW 
Dx 

DRESR3 

Dx« 
DNUMSEG 
Dx 

DRESR4 

Dx« 
DSTART1 
Dx 

DEND1 

Dx 
DNUMBYTES1 
Dx 

DRESR5 

Dx« 
DBITMAP1A 
DBITMAP1B 
DBITMAP1C 
DBITMAP1D 
DBITMAP1E 
Dx 
DSTART2 
Dx« 

DEND2 

Dx« 
DNUMBYTES2 
Dx« 

DRESR6 

Dx« 
DBITMAP2 
Dx« 


DS 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


** 


200 
Define 1 Role 
9B 0 INZ(1) 
Reserved field 
9B © INZ(Q) 
Version 1 struct 
2 INZ(X'0100') 
Length of role 
2 INZ(X'QO6D') 
Description of role 
20 INZ(' ) 
Checksum is not used 
2 INZ(X'0000') 
Reserved field 
2 INZ(X'0000') 
Role Name is DEFAULT expressed in ASCII 
8 INZ(X'44454641554C5420') 
Authentication strength is set to 0 
2 INZ(X'Q000') 
Lower time is 00:00 
1 INZ(X'00') 
1 INZ(X'00') 
Upper time is 23:59 
1 INZ(X'17') 
1 INZ(X'3B') 
Valid days of week 
1 INZ(X'FE') 
Reserved field 
1 INZ(X'00') 
2 Access control points segements are defined 
2 INZ(X'0002') 
Reserved field 
2 INZ(X'Q000') 
Starting bit of segment 1 is 0. 
2 INZ(X'0000') 
Ending bit of segment 1 is 295 (Hex 127). 
2 INZ(X'0127') 
37 Bytes in segment 1 
2 INZ(X'0025') 
Reserved field 
2 INZ(X'00') 
Segment 1 access control points 
INZ(X'Q003FOFD80003000' ) 
8 INZ(X'80001900C0000000' ) 
8 INZ(X'000A8000882F7110') 
8 
5 


co 


INZ(X'1804033180000000' ) 
INZ(X'FF7FFFFF80') 
Starting bit of segment 2 is 512 (Hex 200). 
2 INZ(X'0200') 
Ending bit of segment 2 is 575 (Hex 23F) 
2 INZ(X'023F') 
8 Bytes in segment 2 
2 INZ(X'0008') 
Reserved field 
2 INZ(X'0000') 
Segment 2 access control points 
8 INZ(X'F8007FFF7FFFE60F') 


DA KRRKKKKKKK KER KKK KEK KKK ERK KERR ERK KERR RK RR KERR ERR RR ER KERR ERE 


D* Prototype for Access Control Initialize (CSUAACT) 


DARK RK KKK KKK KER KK KEK KKK ERK KKK KERR KK ERK RRR KEK KR ER KEKE RR KKK ERERK 


DCSUAACI 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DRARRAYCT 


PR 


9B 0 
9B 0 
9B 0 
4 

9B 0 
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DRARRAY 16 

DVRBDTALEN1 9B 0 

DVRBDTA1 4 

DVRBDTALEN2 9B 0 

DVRBDTA2 200 

Dx 

Dxeesee esas eos sceee se le caso esses see eee ee ese sees esate nce 
D* ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

DxeeSeSSee esa - Sasa a a = eee Sa ae aa saa SS Sa eee Sasa SSeS = 
DMSG S 64 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(64) 

D DS 

DMSGTEXT 1 64 

DFAILRETC 41 Ag 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' | 
DMESSAGEFTLE S 21 INZ(' | 
DMSGKEY S 4 INZ(' 2) 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 

CR KKK KK KK KKK KK KKK KR EKER KER ERK KK EKER RRR EKER EKER KERR ERE RRR ERR ERE 
Cx START OF PROGRAM * 
Cx* * 
CkxaSSeoceecee Sasa aas se aS ees feee See Sa Ses ea Soe ase See * 
Cx Set the keywords in the rule array * 
CktsesSeecreceassl esse sscecee ses sess eee secee cscs Sees ase es * 
C MOVEL "INIT-AC ' RULEARRAY 

C MOVE "REPLACE ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 


CR KKK KK KK KEK KKK KKK KR EKER KER ERE KK EKER KR KEKE ER EKER KERR ERE RR RKERREERE 


C* Call Access Control_Initialize SAPI 


CR KKK KKK KKK KK KKK KR EKER KKK ER KKK KK ER KKK RK KERR EKER KERR ER ERK REK ERR 


C CALLP CSUAACI (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT : 
C RULEARRAY : 

C VERBDATALEN1: 
C VERBDATA1: 

C VERBDATALEN2: 
C VERBDATAZ2) 
Cxseeeseeeecescseeeeecese * 

Cx Check the return code * 

(teessseeeereceeeessesees * 

C RETURNCODE IFGT 4 

Cx Vestas see ee seeeeeeeens * 

Cx * Send failure message * 

Cx Feeeeeeseceeacseesseeseas * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

Ce ee ee eee * 

Cx * Send success message * 

Cx Feces esseceseesoseaese= * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx« 
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C ENDIF 

Cx* 

C SETON LR 
Cx« 

CK KKH K KKK KKK KKK KKK KKK KKK KKK KK KKK KER KKK KK KEKE RK KKK ERR ERR ERE 


Cx Subroutine to send a message 
CK KK KK KEKE KKK KEK KER EKER KER ERE RRR KER KERR EKER ER ERK RR ERE RE RR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 
CSUAACI failed with return/reason codes 9999/9999. 
The Default role was successfully set. 


Example: ILE C program for changing an existing profile for your 4758 
Coprocessor 

Change this program example to suit your needs for changing an existing profile for your 4758 
Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


JRassesscassesetscssesssetseccssscsseseeseeeseessee coset ssssseHssess= */ 
/* Change certain fields in a user profile on the 4758 x/ 
/* card. This program changes the expiration date using a new x/ 
/* date in the form YYYYMMDD. x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. x/ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CHG_PROF) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is x/ 
/* already identified either by defaulting to the CRPO1 x*/ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* x/ 
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/* The Common Cryptographic Architecture (CCA) verb used is */ 


/* Access Control_Initialization (CSUAACI). */ 
/* */ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(CHG_PROF) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CHG PROF) MODULE (CHG_PROF) */ 
/* BNDSRVPGM(QCCA/CSUAACI) x/ 
/* */ 
/* Note: Authority to the CSUAACI service program in the x/ 
/* QCCA library is assumed. */ 
/* */ 
/* The Common Cryptographic Architecture (CCA) verb used is x/ 
/* Access Control_Initialization (CSUAACI). */ 
/* */ 
/ReSeSSeee epee sae See cheese Steer ae tees eeeae eee eee eee tesa seeseeee «/ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries */ 


#include <stdio.h> 

#include <string.h> 
#include <stdlib.h> 
#include <decimal.h> 


[#eereSeedeeeesseseSeec ses epee e eee eet see ea eeee eee eee ee ceseoSeseees «/ 
/* standard return codes */ 
Peoee sano saoenes es ses a= eeas sae =o See a a ee ea ease */ 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


| Reeeaeesdeceressesesreaeer aoe 2 see aeeses oa see— rane sao esesseS sees sees «/ 
/* standard CCA parameters */ 
[#essser soso eenaessecsaceseere Se eeseceen eet eae eee eS «/ 


long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[8]; 

long rule_array_count = 1; 


| ReeaebcesestessassSeessesessesenesaeeedeee acess ese sseeeeceoseescee= «/ 
/* fields unique to this sample program */ 
[ #eseeeceseaseseese sesh ese eee eese eee eee beeeeeetesse ces seen etcees «/ 


long verb_data_length; 

char * verb_data; 

long verb_data_length2; 

char * verb_data2; 

memcpy (rule_array, "CHGEXPDT",8) ; /* set rule array keywords */ 
verb_data_length = 8; 

verb_data = "SECOFR1 "; /* set the profile name */ 
verb_data_length2 = 8; 


verb_data2 = "20010621"; /* set the new date */ 
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/* invoke verb to change the expiration date in specified profile */ 


CSUAACI( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data, 
&verb_data_length2, 
verb_data2); 


if ( (return_code == OK) | (return_code == WARNING) ) 

{ 

printf("Profile expiration date was changed successfully"); 
printf(" with return/reason codes "); 

printf ("%ld/%ld\n\n", return_code, reason_code); 
return(OK); 

} 


else 

{ 

printf("Change of expiration date failed with return/"); 
printf("reason codes "); 

printf(" %1d/%ld\n\n", return_code, reason code); 
return(ERROR) ; 
} 


Example: ILE RPG program for changing an existing profile for your 4758 
Coprocessor 

Change this program example to suit your needs for changing an existing profile for your 4758 
Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRAKKKKKK KK ERK KEKE KKK KERR KERR ERK RRR RRR RRR RR ER KEKE EKER ERR RRR 
D* CHG_PROF 

Dx« 

D* Change certain fields in a user profile on the 4758 

D* card. This program changes the expiration date using a new 
D* date in the form YYYYMMDD. 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

D* Parameters: Profile 

Dx« 

D* Example: 
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D* CALL PGM(CHG_PROF) PARM(PROFILE) 


Dx« 


Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CHG_PROF) SRCFILE(SAMPLE) 
D* CRTPGM PGM(CHG PROF) MODULE(CHG_PROF) 


D« BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUAACI service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Access Control Initialize (CSUAACI) 


Dx« 


D* This program assumes the card with the profile is 

D* already identified either by defaulting to the CRPO1 

D* device or by being explicitly named using the 

D* Cryptographic_Resource Allocate verb. Also this 

D* device must be varied on and you must be authorized 

D* to use this device description. 

DA RRKKKAKK KK KKK KKK KKK KK ERK KKK KKK KKK KEK KERR KEK KR ER KERR ERK RR RER RRR ERE 


Dx« 
DRETURNCODE 
Dx 
DREASONCODE 
Dx« 
DEXITDATALEN 
Dx« 

DEXITDATA 

Dx« 
DRULEARRAYCNT 
Dx 

DRULEARRAY 

Dx« 
DVERBDATALEN1 
Dx 

DVERBDATA1 

Dx« 
DVERBDATALEN2 
Dx« 

DVERBDATA2 

Dx 

Dx« 


** Return code 

S 9B 0 

** Reason code 

S 9B 0 

xx Exit data length 

S 9B 0 

xx Exit data 

S 4 

** Rule array count 

S 9B 0 

** Rule array 

S 16 

** Verb data 1 length 

S 9B 0 INZ(8) 
** Verb data 1 

S 8 

** Verb data 2 length 

S 9B 0 INZ(8) 
xx Verb data 2 

S 8 


DA KRKKKKKKK KK KK KKK EK KKK E RRR ERR KK KERR RRR RRR RR ERK RRR KERR ERE 


D* Prototype for Access Control_Initialize (CSUAACI) 


DA KRKKKKKK KK KKK KKK EK KKK KERR KKK KKK KKK KEK KERR KKK KER KKK ERK RR ERKEEK 


DCSUAACI 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DRARRAYCT 
DRARRAY 
DVRBDTALEN1 
DVRBDTA1 
DVRBDTALEN2 
DVRBDTA2 

Dx« 


DMSG 
DMSGLENGTH 
D 


PR 


** Declares for sending messages to the 
** job log using the QMHSNDPM API 


75 DIM(2) CTDATA PERRCD(1) 
9B 0 INZ(75) 
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DMSGTEXT 1 75 

DFAILRETC 4l 44 

DFAITLRSNC 46 49 

DMESSAGEID 7 INZ(' ') 

DMESSAGEFTLE 21 INZ(' 

DMSGKEY 4 INZ(' ty 

DMSGTYPE 10 INZ('*INFO 

DSTACKENTRY 10 INZ('* 

DSTACKCOUNTER 9B 0 INZ(2) 

DERRCODE 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

CRRA KK KEKE KKK KKK KKK EKER KEK ERE KK RK EKER KEKE RR ERE RRR EKR ERK RR ERR ERE 

Cx START OF PROGRAM * 

Cx * 

Ck¥SeeSstseseeeseeeee see eae eee ee eee S Soe eee eee ee eee eee * 

Cx Parameter is profile to be changed. * 

CkSt Se scseeSebeee ees ese ess ceebece eet eee eae ese ce cee emcee see * 

C *ENTRY PLIST 

C PARM VERBDATA1 

CkseetSese teense ee See Sense eee ee eee See eee ee eee tee See * 

Cx Set the keywords in the rule array * 

(C¥eeeeSSa eae see see sa eo aaa a a ea ae = Se ae ae eae ses] — SSeS * 

C MOVEL "CHGEXPDT' RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

Ceseetesse leeeeceeee See sec sleep e cease ee Sect eee ee ee see Scee * 

Cx Set new expiration date * 

(eee a ee eet ee * 

C MOVEL '20061231' VERBDATA2 

CkSae SaaS 2SaSee eae see sa saan aa eSaas aa = SSeS See aes es===S—e5 * 

C* Call Access _Control_Initialize SAPI * 

ee ee ee ere * 

CALLP CSUAACI (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT : 
RULEARRAY : 
VERBDATALEN1: 
VERBDATA1: 
VERBDATALEN2: 
VERBDATA2) 


DANNNNYN 
LYS 


Cy 


QOOVGAAA AO: 


C MOVE MSG(1) MSGTEXT 
C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 


C MOVE MSG (2) MSGTEXT 
C EXSR SNDMSG 


C ENDIF 
C SETON 
Cx* 


CR KKK KKK KKK KK KKK KR KK EK KEK ERE KK RK ER KEK KKK KERR ERE RRR REKRE RE RREKREERE 
Cx Subroutine to send a message 
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LR 


CR KKK KKK KKK KK KKK KEKE KEK KKK ERK KK KK ER KKK EKER ERE RR RR ERE RRR RR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


** 
CSUAACI failed with return/reason codes 9999/9999' 
The request completed successfully 


Set the environment ID and clock 
The Environment ID (EID) 


Your 4758 Coprocessor stores the EID as an identifier. The easiest and fastest way to set the EID is to 
use the 4758 Cryptographic Coprocessor configuration web-based utility found off of the iSeries Tasks 
page at http://server-name:2001. The utility includes the Basic configuration wizard that is used when the 
Coprocessor is in an uninitialized state. If the 4758 Coprocessor already has been initialized, then click on 
Manage configuration and then click on Attributes to set the EID. 


If you would prefer to write your own application to set the EID, you can do so by using the 
Cryptographic_Facility_Control (CSUACFC) API verb. Two example programs are provided for your 
consideration. One of them is written in ILE C, while the other is written in ILE RPG. Both perform the 
same function. 


* |“Example: ILE C program for setting the environment ID on your 4758 Coprocessor” on page 64 
* |“Example: ILE RPG program for setting the environment ID on your 4758 Coprocessor’” on page 66 


Your 4758 Coprocessor copies the EID into every PKA key token that your 4758 Coprocessor creates. The 
EID helps the 4758 Coprocessor identify keys that it created as opposed to keys that another 4758 
Coprocessor created. 


The Clock 


The 4758 Coprocessor uses its clock-calendar to record time and date and to determine whether a profile 
can log on. The default time is Greenwich Mean Time (GMT). Because of its function, you should set the 
clock inside your 4758 Coprocessor before removing the default role’s capability of setting it. 


The easiest and fastest way to set the clock is to use the 4758 Cryptographic Coprocessor configuration 
web-based utility found off of the iSeries Tasks page at http://server-name:2001. The utility includes the 
Basic configuration wizard that is used when the Coprocessor is in an uninitialized state. If the 4758 
Coprocessor already has been initialized, then use click on Manage configuration and then click on 
Attributes to set the clock. 


If you would prefer to write your own application to set the clock, you can do so by using the 
Cryptographic_Facility_Control (CSUACFC) API verb. Two example programs are provided for your 
consideration. One of them is written in ILE C, while the other is written in ILE RPG. Both perform the 
same function. 


* |“Example: ILE C program for setting the clock on your 4758 Coprocessor” on page 68 
* |“Example: ILE RPG program for setting the clock on your 4758 Coprocessor’ on page 71 
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Example: ILE C program for setting the environment ID on your 4758 Coprocessor 
Change this program example to suit your needs for setting the environment ID on your 4758 
Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


[Besse ase ace aes eso see see ss Soe se Sere sees aos hea Sees ees 2 ss4=- So oSa5 */ 
/* Set the environment ID on the 4758 card, based on a */ 
/* 16-byte sample value defined in this program. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. x/ 
/* x/ 
/* Parameters: */ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(SETEID) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 x/ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(SETEID) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(SETEID) MODULE(SETEID) */ 
/* BNDSRVPGM(QCCA/CSUACFC) */ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facilites Control (CSUACFC). x/ 
/* x/ 
[xeseescassssanseesenseseee tessa ea see eee ease ste seneea es Se seoeesassne */ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries */ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


Jeasecsseseeeceesecesl senses secseesseseesas anaes scesossesa oS sens sess */ 
/* standard return codes */ 
[eeeeesSesse esses eeseeeteeasoscseseSanes see secesneeeeneseeeoesces—ces «/ 
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#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 


long verb_data_length; 
char * verb_data = "SOME ID data 160"; 


/* set keywords in the rule array 
memcpy(rule_array,"ADAPTERISET-EID ", 16); 
verb_data_length = 16; 

/* invoke the verb to set the environment ID 


CSUACFC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data); 


if ( (return_code == OK) | (return_code == WARNING) ) 


printf("Environment ID was successfully set with "); 


return(0K) ; 


} 


else 


return(ERROR) ; 


} 


*/ 


ee ee «/ 


ASS RR SRS eee «/ 


*/ 


caine areata ae enen nents «/ 


printf("return/reason codes %1d/%ld\n\n", return_code, reason code); 


printf("An error occurred while setting the environment ID.\n"); 


printf ("Return/reason codes %ld/%ld\n\n", return_code, reason_code); 
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Example: ILE RPG program for setting the environment ID on your 4758 


Coprocessor 
Change this program example to suit your needs for setting the environment ID on your 4758 


Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA RRA KKKKK KK KEK KK KKK KKK KERR KKK RK KKK RRR KERR KKK KER RK RRR KERR RRR KEKE 
D* SETEID 

Dx« 

D* Set the environment ID on the 4758 card, based on a 

D* 16-byte sample value defined in this program. 

Dx 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(SETEID) 

Dx 


Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(SETEID) SRCFILE(SAMPLE) 
D* CRTPGM PGM(SETEID) MODULE(SETEID) 


Dx BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


Dx« 

DA KRRKKKKKKK KEKE KKK KKK KERR RE K RRR KERR RE RRR KERR ER KERR ERE KR RRR RE RRERER 
Pksceeceseelocesececw se sssscossoseeSeee cece Sceoess 
D* Declare variables for CCA SAPI calls 

Pkaseececees ee ece ects ces eeee eee eee see seo eee see 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Verb data length 
DVERBDATALEN S 9B 0 

D* «x Verb data 

DVERBDATA S 16 INZ('Card ID 01234567') 
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Dx« 

Dx« 

DA KRKKKKKKK KKK KEK KK ERK KERR KEKE RRR KERR RRR RRR RR RER KEK RR KEKE REE 
D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DA KRKKKKK KKK KKK KKK ERK KK ERK KKK KKK KERR KK KERR KKK KERR KERR KKK ERKE ER 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 16 

Dx« 

Drees eee eee cease cee ee eee ee eee eee eee ee ee See eee See See ee 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 
DPkeessecoasossceecesclesscsecsscecesessiss se sesso S ese ceeSeossece 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAITLRSNC 46 49 

DMESSAGEID 5 7 INZ(' ") 
DMESSAGEFTLE S 21 INZ(' ") 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ) 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(Q) 

DBYTESOUT 5 8B 0 INZ(0) 

C* 

CR KKK KK KK KKK KK KKK KR ERE RK ER ERK KK RK ERK RR ERR ER EKER RR ERE RK RR ERR ERE 
Cx START OF PROGRAM * 
Cx* * 
CxsesccSeessssseslcesceessossesscsoscsossecssossessscsnes sss esece * 
Cx Set the keyword in the rule array * 
CkesSeee cece eco ee ete Se eee cess Sees ee eee tse ce see eee * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE 'SET-EID ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

CXeteereeseee sess esse Seca ee ace ese ease seen e Se ase esses eeecees * 
Cx Set the verb data length to 16 * 
Cxkeccseccssessssectecesccceseoleeccou sesso csesseseosssceess se * 
C Z-ADD 16 VERBDATALEN 

CR KKK KK KKK KKK KEKE KR EKER KER ERE KK EKER KERR EKER ER ERR RR ERE RR RRE REE 
Cx Call Cryptographic Facilty Control SAPI x/ 
CR KKK KK KKK KKK KEKE KR EKER KER ER KERR RK ERK EKER EER ER ERR RR ERE RRR E REE 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

Cc RULEARRAYCNT : 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 

(terest sseeenecsecssesces * 

Cx Check the return code * 

Ck¥eeesese sce eee sees cece * 

C RETURNCODE IFGT 4 

Cx Peeccee secs sesseeeseeee * 

Cx * Send error message * 

Cx {cccciaaceacesceoesacees * 

C MOVEL MSG(1) MSGTEXT 
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C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 

Cx 

C ELSE 

Cx Kecsseseesscssclacssose * 

Cx * Send success message * 

Cx Peicseesteceeeceence cess * 

C MOVE MSG(2) MSGTEXT 
C EXSR SNDMSG 

Cx 

C ENDIF 

Cx* 

C SETON LR 
Cx« 


CR KKK KK KEKE KKK KEK KKK EKER KER ERE KKK ERE RR EK ERR ER ERE RR ERE RRR ERR 


Cx Subroutine to send a message 
CR KKK KK KEKE KKK KKK KKK EKER KER ERE RRR KEKE RR EK ERR ERE RRR ERE REE EKER 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

¢ PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
¢ PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 


CSUACFC failed with return/reason codes 9999/9999. 
The Environment ID was successfully set. 


Example: ILE C program for setting the clock on your 4758 Coprocessor 
Change this program example to suit your needs for setting the clock on your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


| a a a er «/ 
/* Set the clock on the 4758 card, based on a string from */ 
/* the command line. The command line string must be of */ 
/* form YYYYMMDDHHMMSSWW, where WW is the day of week (01 */ 
/* means Sunday and 07 means Saturday). */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x*/ 
/* char * new time 16 characters */ 
/* x/ 
/* Example: */ 
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/* CALL PGM(SETCLOCK) PARM('1999021011375204') */ 


/* x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this */ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. */ 
/* x/ 
/* Use these commands to compile this program on iSeries: x*/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(SETCLOCK) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(SETCLOCK) MODULE (SETCLOCK) x/ 
/* BNDSRVPGM(QCCA/CSUACFC) */ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the */ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facilities Control (CSUACFC). x/ 
/* */ 
[eo eee ae eee a sas ae Se ae a Se ee ee eae */ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 

/* Service Provider for iSeries */ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


| ee ee ee et */ 
/* standard return codes */ 
esses seadesaossassasacse Se sasesecssecesseese sss Ssseseseuses sceeesae ss «/ 


#define ERROR -1 

#define OK 0 

#define WARNING 4 

void help(void) 

{ 
printf("\n\nThis program loads the time and date into the 4758 card.\n"); 
printf("It requires a single command line parameter containing the \n"); 
printf("new date and time in the form YYYYMMDDHHMMSSWW, where WW is the\n"); 


printf("day of the week, 01 meaning Sunday and 07 meaning Saturday.\n\n"); 


int main(int argc, char *argv[]) 


{ 


eesessssesscsseSecsecnsscssssecssesee ses seessoseseeessseseesscsecses «/ 
/* standard CCA parameters */ 
| $eeseesesost eee ass See se Ss Sesenesoeeetecescesaaesesseeeececseessee= «/ 


long return_code 
long reason_code = 0; 


iT 
o 


long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 


Chapter 5. 4758 Cryptographic Coprocessor for iSeries 


69 


70 


long verb_data_length; 
char * verb_data; 


if (argc != 2) 
{ 


help(); 


return(ERROR) ; 
} 


if (strlen(argv[1]) != 16) 
{ 


printf("Your input string is not the right length."); 


help(); 


return(ERROR) ; 


/* set keywords in the rule array 

memcpy (rule_array, "ADAPTERISETCLOCK", 16) ; 
verb_data_length = 16; 

/* copy keyboard input for new time 

verb_data = argv[1]; 

/* Set the clock to the time the user gave us 


CSUACFC( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data) ; 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 
printf("Clock was successfully set.\nReturn/"); 


printf("reason codes %1ld/%ld\n\n", return_code, reason_code) ; 


return (OK); 


} 

else 

{ 
printf("An error occurred while setting the clock.\nReturn") ; 
printf("/reason codes %1d/%ld\n\n", return_code, reason_code) ; 
return (ERROR) ; 

} 


iSeries: Cryptographic hardware 


*/ 


Example: ILE RPG program for setting the clock on your 4758 Coprocessor 
Change this program example to suit your needs for setting the clock on your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKKKKK KKK KKK KKK KK ERK KKK KKK KER KKK ERK KR RRR KK RR KEK RR EER RRR RK 


Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx 
Dx 
Dx 
Dx« 
Dx« 
Dx« 


DA RRAKK KKK KKK KKK KKK ERK KK ERK KKK KKK KKK KK KEKE KKK RE RK RRR KKK RR RRKRRERE 


SETCLOCK 


Set the clock on the 4758 card, based on a string from 
the command line. The command line string must be of 
form YYYYMMDDHHMMSSWW, where WW is the day of week (01 
means Sunday and 07 means Saturday) . 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 


consideration. These example has not been thoroughly 
tested under all conditions. IBM, therefore, cannot 


guarantee or imply reliability, serviceability, or function 


of these programs. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


these programs and files. 


Note: Input format is more fully described in Chapter 2 of 


IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: 
char * new time 16 characters 


Example: 
CALL PGM(SETCLOCK) PARM('2000061011375204') 


Use these commands to compile this program on iSeries: 

CRTRPGMOD MODULE(SETCLOCK) SRCFILE(SAMPLE) 

CRTPGM PGM(SETCLOCK) MODULE (SETCLOCK) 
BNDSRVPGM(QCCA/CSUACFC) 


Note: Authority to the CSUACFC service program in the 
QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verbs used are 


Cryptographic_Facilty Control (CSUACFC) 


Deeeseeaesneetas scot see ce Se sees oe eee soe Sse lols 
Dx Declare variables for CCA SAPI calls 
DkerecesossesscescesceeSecScscssesessoesessasscsese 
Dx *x Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Verb data length 
DVERBDATALEN S 9B 0 

D* «x Verb data 
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DVERBDATA S 16 

Dx« 

DAKAR KK KKKKK KEK KKK ERK KEKE KKK KERR RK KERR REE RE KERR ER KERR ER KERR RERER 
D* Prototype for Cryptographic_Facilty_Control (CSUACFQ) 


DA KRAKKKKK KK KER KKK KEK KKK ERK KKK KERR KEKE RK KKK KKK KER KEKE RK KERR 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 16 

Dx 

PkiesSetees eee secre See ae ee eee ee Se eee eee eee eee eee Sees 
Dx ** Declares for sending messages to the 
Dx ** job log using the QMHSNDPM API 
DPeesesSssSesssescccossessessccse ses cl eeecssese sce sescososeoes 
DMSG S 75 DIM(6) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 


CR KKK KK KEKE KK KKK KKK EKER KEK ERE KK RK EKER KER ERR ER ERR RR ERE RRR EKER 


Cx START OF PROGRAM 

Cx« 

C *ENTRY PLIST 

C PARM VERBDATA 

Cx 

Ck eee eee e eres e ee see eee eee eee eee eee eee eee eee sees 
Cx Check the number of parameters passed in 
Gkesctescsssesecssssesssssc ss esstccccc ses ecse sess essessSsSeeses 
C IF (%PARMS < 1) 

Cx Pest see See eee ee eee ce cele ee eee eee eee 
Cx * Send message describing the format of the parameter 

Cx Hes eeS Sas SSeS ae eee aa aa a a a a aa ee ee as eee e 


C MOVEL MSG(3) MSGTEXT 

C EXSR SNDMSG 

C MOVEL MSG(4) MSGTEXT 

C EXSR SNDMSG 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C MOVEL MSG (6) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

C* 

GkseSeSese acest esi esses sece ee oss esse eee sete eae eae sees 
Cx Set the keyword in the rule array 
Gkecteasseteccssceoe otek seSsessessocecsssssecssesise sss Secseese 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "SETCLOCK' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

CkBeR Sea e eS Seas ses ae esas ee seas as esessaeSseoseesee Se seeseseS—s= 


Cx Set the verb data length to 16 
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* 
* 


C Z-ADD 16 VERBDATALEN 

CR KKK KK KEKE KK KK KKK KR EKER KER ER KKK EKER KERR EKER EKER KERR ERE RK RK ERR ERE 
Cx Call Cryptographic Facilty Control SAPI */ 
CRRA KKK KKK KKK KKK RE KEK KEK ERK KK EKER KKK RK KERR EKER KERR ERE RE RK ERR ERE 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

Cc RULEARRAYCNT : 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 
(eee eee * 

Cx Check the return code * 

(Ctescsseemeeeessecese ssn * 

C RETURNCODE IFGT 4 

Cx Paecene seen sess eee sane * 

Cx * Send error message * 

Cx Weece oe eee eee esses eee * 

C MOVEL MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx* et os ele * 

Cx * Send success message * 

Cx« (sco cacuseuSseaesceeace * 

C MOVE MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ENDIF 

Cx« 

C SETON LR 
Cx 


CR KKK KK KKK KKK KEKE KR EKER KER ERE KK EKER KKK ERE RR ER ERR RR ERE RR ERE RRR 


Cx Subroutine to send a message 
CK KKK KKK KKK KKK KKK KEKE KK EK ERK KK EKER KKK EKER KER ERK RR EKER KERR ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


*K* 

CSUACFC failed with return/reason codes 9999/9999. 

The request completed successfully. 

This program loads the time and date into the 4758 card. 

It requires a single command line parameter containing the 

new date and time in the form YYYYMMDDHHMMSSWW, where WW is the 
day of the week, 01 meaning Sunday and 07 meaning Saturday. 


Load a function control vector 


After|“Create and define roles and profiles” on page 25} you must load a function control vector (FCV) for 


your 4758 Coprocessor. Without it, your 4758 Coprocessor will be unable to perform any cryptographic 
operations. 
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A function control vector is a digitally signed value stored in a file provided by IBM. When you install one 
of the 5722-ACx Cryptographic Access Provider products, the file is stored in the root file system with a 
path of /QIBM/ProdData/CAP/FCV.CRT. This value enables the cryptographic application within the 4758 
Coprocessor to yield a level of cryptographic service consistent with applicable import and export 
regulations. 


The easiest and fastest way to load the FCV is to use the 4758 Cryptographic Coprocessor configuration 
web-based utility found off of the iSeries Tasks page at http://server-name:2001. The utility includes the 
Basic configuration wizard that is used when the Coprocessor is in an uninitialized state. If the 4758 
Coprocessor already has been initialized, then click on Manage configuration and then click on 
Attributes to load the FCV. 


If you would prefer to write your own application to load the FCV, you can do so by using the 
Cryptographic_Facility_Control (CSUACFC) API verb. Two example programs are provided for your 
consideration. One of them is written in ILE C, while the other is written in ILE RPG. Both perform the 
same function. 


“Example: ILE C program for loading a function control vector for your 4758 Coprocessor” 


“Example: ILE RPG program for loading a function control vector for your 4758 Coprocessor’ on 
page 77 


Two other example programs are provided that show how to clear the function control vector. One of them 
is written in ILE C, while the other is written in ILE RPG. 


“Example: ILE C program for clearing a function control vector from your 4758 Coprocessor” on page 81 


“Example: ILE RPG program for clearing a function control vector from your 4758 Coprocessor” on 
page 83 


After you load a function control vector for your 4758 Coprocessor, you can load and set a master key 
using|“Load and set a master key” on page 85)to use to encrypt keys. 

Example: ILE C program for loading a function control vector for your 4758 
Coprocessor 


Change this program example to suit your needs for loading a function control vector for your 4758 
Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
*/ 


| $osecencewesuassssaseeseessssesssteesessssssesatessoseaescea= 
/* Load the Function Control Vector into the 4758 card. x/ 
/* The Function Control Vector enables the cryptographic */ 
/* functions of the 4758 card and is shipped with the x/ 
/* Cryptographic Access Provider products. x/ 
/* */ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 

/* x/ 


/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly  */ 


/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or functionx/ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services forx/ 


/* these programs and files. x/ 
/* x*/ 
/* Note: The Function Control Vector is stored in an IFS x/ 
/* file owned by the system. The format of this x*/ 
/* vector is described in an appendix of the x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
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/* Parameters: x/ 
/* none. x/ 
/* x/ 
/* Example: x/ 
/* CALL PGM(LOAD_FCV) x/ 
/* */ 
/* Note: This program assumes the device you want to load is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized +*/ 
/* to use this device description. */ 
/* x/ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(LOAD_FCV) SRCFILE(SAMPLE) SYSIFCOPT(*IFSIO) */ 
/* CRTPGM PGM(LOAD_FCV) MODULE(LOAD_FCV) + x/ 
/* BNDSRVPGM(QCCA/CSUACFC) x/ 
/* */ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Cryptographic_Facility Control (CSUACFC) x/ 
/* x/ 
[exes Saree eee sas Sess e ses eS ot eee eee seeeeSeSe eee eee ee case «/ 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <decimal .h> 
#include "csucincl.h" 


#pragma linkage(QDCXLATE, OS, nowiden) 


void QDCXLATE(decimal (5,0)*, 
char *, 
char *, 
char *); 


int main(void) 


#define ERROR -1 
#define OK 0 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 


/* header file for CCA Cryptographic 
Service Provider for iSeries 
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/* fields unique to this sample program */ 


long verb_data_length; 

char *verb_data; 

char buffer[1000]; 

char description[81]; 
decimal(5,0) descr_length = 80; 
int num_bytes; 

FILE *fcv; 


[#esesscesssesese so seeesere ease een see ee nese ease ace asses oeesceeassse «/ 
/* retrieve FCV from IBM supplied file */ 
ee ee ee eee ee ee ee eee eee */ 


fev = fopen("/QIBM/ProdData/CAP/FCV.CRT", "rb"); 
if (fcv==NULL) 


printf("Function Control Vector file not available\n\n"); 
return ERROR; /* File not found or not authorized */ 


} 


num_bytes = fread(buffer,1,1000, fcv) ; 
fclose(fcv); 


if (num_bytes != 802) 
{ 


printf("Function Control Vector file has wrong size\n\n"); 


return ERROR; /* Incorrect number of bytes read */ 
} 
[ese cesoesesh-Sesesees sen etaSseseds cess esos eeeeseeeseoseossesesees «/ 
/* extract fields in FCV needed by 4758 card */ 
/* Note: use offsets and lengths from CCA publication listed earlier */ 
/ReseeeseseassssSesessaseesceseasseseses as acu senseesesoeesesscuesseas */ 


memcpy(description, &buffer[390] ,80) ; 

description[80] = 0; 

QDCXLATE(&descr_length, description, "QEBCDIC ", "QSYS me 
printf("Loading Function Control Vector: %s\n",description) ; 


verb_data_length = 204; 
verb_data = &buffer[470]; 


rule_array_count = 2; 
memcpy ((char*)rule_array, "ADAPTERILOAD-FCV", 16) ; 


[asec ssensseceseoceosssusecsscsceseeseesesansssSsescse ssa SSsenSes—= */ 
/* Load the 4758 card with the FCV just retrieved */ 
[#eSesseaee ses eSesSase sect assseseeasenseseSseeeene ee toast aceace eee «/ 


CSUACFC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char*) rule_array, 
&verb_data_length, 
verb_data); 


if (return_code != 0) 


printf("Function Control Vector rejected for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; /* Operation failed. */ 
} 
else 


{ 


printf("Loading Function Control Vector succeeded\n\n") ; 
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printf("SAPI returned %1d/%ld\n\n", return_code, reason_code) ; 
return OK; 

} 

} 


Example: ILE RPG program for loading a function control vector for your 4758 


Coprocessor 
Change this program example to suit your needs for loading a function control vector for your 4758 


Coprocessor. 


Note: Read the/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKK KKK KKK KKK KEK KKK RRR KKK KKK KER KK KERR KKK RRR KK RRE KEK RR RER KERR 
D* LOAD_FCV 

Dx 

D* Load the Function Control Vector into the 4758 card. 

D* The Function Control Vector enables the cryptographic 

D* functions of the 4758 card and is shipped with the 

D* Cryptographic Access Provider products. 

Dx« 

D* The Function Control Vector is contained within a stream 

D* file. Before compiling and running this program, you 

D* must copy the contents of the stream file to a database 

D* member. An example of how to do this is shown in the 

D* instructions below for compiling and running this program. 
Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(LOAD_FCV) 

Dx« 

D* Use these commands to compile this program on iSeries: 
Dx« 

D* CRTRPGMOD MODULE(LOAD_FCV) SRCFILE(SAMPLE) 

Dx« 

D* CRTPGM PGM(LOAD_FCV) MODULE(LOAD_FCV) 

Dx BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


Dx« 

DA KRAKKKKKKK KEK KKK ERK KK ERK KERR KERR KERR RRR RRR KR ER KERR ERR RR RERERRRRER 
D¥eeseeeeeesesess assess ccssce see ses ee sse sess scescesesslecs 

D* Declare variables used by CCA SAPI calls 

D¥eeeSeec eee seessee sess lceeeee seca sete sseesesseeseeee ses 

Dx ** Return code 

DRETURNCODE S 9B 0 
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Dx **x Reason code 


DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITTDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA 5 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Verb data length 

DVERBDATALEN S 9B 0 INZ(204) 

Dx ** Verb data 

DVERBDATA S 204 

Deeeies Soa 5 2 See See Se SSeS seo a eee Sas SS oS = SSeS = =e 
D* Declare variables for working with files 

[De ee ee eee ee 
Dx ** File descriptor 

DFILED S 9B 0 

Dx ** File path 

DPATH S 80 INZ('/QIBM/ProdData/CAP/FCV.CRT') 
D* ** Open Flag - Open for Read only 
DOFLAGR S 101 @ INZ(1) 

D* ** Structure of Funciton control vector file 
DFLD1 DS 

DFLDDTA 802 

DDESCR 391 470 

DFNCCTLVCT 471 674 

D* ** Length of data read from file 

DINLEN S 9B 0 

D* ** Declares for calling QDCXLATE API 
DXLTTBL S 10 INZ('QEBCDIC  ') 
DTBLLIB S 10 INZ('QSYS ') 
DDESCLEN S 5P @ INZ(80) 

Dx ** Index into a string 

DINDEX S 5B 0 

Dx ** Variable to hold temporary character value 
DCHAR S 1 

Dx 


DA KRRKKKKKK KK ERK EKER KKK ERK KKK KEKE RE REE RRR KR ERR RR ER KER EERE 


D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DARK AK KKK KKK KER KKK KEK KKK ERK KKK ERK KEKE RK KKK KKK KER KEK KERR KERR 


DCSUACFC PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DRARRAYCT 9B 0 
DRARRAY 16 
DVRBDTALEN 9B 0 
DVRBDTA 204 

Dx« 


DARK AK KKK KKK KER KKK KEK KKK ERK KKK KERR KEKE KEK KERR KEK KR ER KEK KER KEKE 
D* Prototype for open() 

DAKAR KKKKKK KK ERK KEKE KKK KERR KKK RRR KERR RRR RRR RR ER KERR ER KEK RERRERERK 
Dx value returned = file descriptor (OK), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B @ VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U @ VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DARK RK KKK KKK KKK KKK KEK K KKK KEK KK RRR KK RRR KR ERK RRR KER KEKE RRR RRR KK KER KER RRR KERR 
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Dx Prototype for read() 


DA KRKKKKKKK KERR KKK ERK KERR KER KEK KEK KERR RRR RRR RR RER KER RER EKER ERR 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be read 

D 9B 0 VALUE 

Dx 


DA KRKKKKKKK KERR KKK KEK K KEKE KEKE KR KK RRR RK KERR KERR RR KERR RRR ERR RK KERR RERKER RRR 


D* Prototype for close() 


DA KRKKKKKKK KER KKK KEK KKK KKK KKK KKK KER KK RE RK RRR KERR RRR RR E RK KR ER KEK RRR KR ER 
D« value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

D* File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

Dees Seo SSa Ses Se SoS a ee eae a a Se ie Sas = Se = SS = Se 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
DxeSeaSeeSeseSesasoSseoea Sasa aeseS sas seSae Saas aa aSSesSa—s55=SS55= 
DMSG S 80 DIM(4) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(80) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 4l 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFTILE S 21 INZ(' ") 
DMSGKEY S 4 INZ(' t) 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B © INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CR KKK KKK KEK KKK KKK KR ERE RK ER ERK KK EKER KERR EK EER ER ERE RR EKER KERR ERRERE 
Cx START OF PROGRAM * 
Cx * 
CxeSsaSsetacesosasso—s-a5]s-— seas Sasso —aoease> Sees ==Se=—=55 >= * 
Cx Open the FCV file * 
C¥eeeshsseseessedesseseeeseesensseeeeteneseeseseeeeeesesseeres * 
Cx Poeeeeeceeedeese seca ess eses * 

Cx »** Null terminate path name * 

Cx Pe see eee eee see ee eee eee eres * 

C EVAL %SUBST(PATH:27:1) = X'Q0' 

Cx (Ce ceiecusaeeeeoececcecelS * 

Cx »* Open the file * 

Cx* }iresesossessccooescece * 

C EVAL FILED = open(PATH: OFLAGR) 

Cx* is eases aan Sit eth es ee * 

Cx »* Check if open worked * 

Cx* keoceeeewesseaceecsses cs * 

C FILED IFEQ -1 

Cx« hesseeees cesses osssceseesescceoeeass * 

Cx * Open failed, send an error message * 

Cx Fivesweecehasseseseasenesteseeesess= * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C* 

C ENDIF 

Cx* seeeeee ee ssoseece sess Ses SeS eee See ae eee aaa eeeeeeez eas * 


Cx * Open worked, read the FCV, and close the file * 
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C Z-ADD 802 INLEN 

C EVAL INLEN = read(FILED: FLDDTA: INLEN) 
C CALLP close (FILED) 

Cx« 

Cx« oa saoca scans e eens coneoesonecaasaces * 

Cx * Check if read operation was OK * 

Cx i i a sa ea mre * 

C INLEN IFEQ -1 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 
eee ee eee ee * 
Cx Copy the FCV to the verb data parameter. * 
C¥seSesSsi ose cases tesa cess sSee esse slee se ece aces seen ceelese * 
C MOVEL FNCCTLVCT VERBDATA 
CxkSSeeSsssssessestcccoosessessesscsessc Sess sSeeSssScsesesl esses ce] * 
Cx Convert description to EBCDIC and display it * 
Ckstetectecceseeesc eee aa seee tee eee Sl ese see cee eee oe Sees * 
C CALL "QDCXLATE' 

C PARM DESCLEN 

C PARM DESCR 

C PARM XLTTBL 

C PARM TBLLIB 

C MOVEL DESCR MSGTEXT 

C Z-ADD 80 INDEX 
Ckecelcosoesessessssecseasesscscseese cc esceseeoeesssssstesceeces * 
Cx Replace trailing null characters in description * 
Cx with space characters. * 
Oe ee ee ee eee eee eo * 
C SETOFF 50 
C DOU *IN50 

C EVAL CHAR = %SUBST (MSGTEXT: INDEX: 1) 

C CHAR IFNE X'0Q' 

C SETON 50 
C ELSE 

C EVAL %SUBST(MSGTEXT: INDEX:1) = ' ' 

C SUB 1 INDEX 

C INDEX IFEQ 0 

C SETON 50 
C ENDIF 

C ENDIF 

C ENDDO 

C EXSR SNDMSG 
CxkxseeessSoceecescscesscesessoscowe ele esc esscsssosiscsssSscseess * 
Cx Set the keywords in the rule array * 
CxktteSeceeSeseeee ese reee see ce See ee eee ese sees epee see cee cscs * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "LOAD-FCV' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

CR KKK KKK KKK KK KEKE KR KK EK KKK ERE KK EKER KEK KKK KERR ERE RR RR ERE RE RK ERR RERE 
Cx Call Cryptographic Facilty Control SAPI */ 
CR KKK KK KEKE KKK KEKE KKK KER KER ERE KKK ERE RR EK ERR ER ERE RR ERE RE RK ERREERE 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 

Ck *eceesesssescscesscesece= * 

Cx »* Check the return code * 

Ck Rececesesesseeseesessesas * 

C RETURNCODE IFGT 0 
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Cx * Send failure message * 

Cx Pe eee eee Seee eee ss * 

C MOVEL MSG (3) MSGTEXT 

C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 

Cx* 

C ELSE 

Cx« 

Cx« laconic aecoccesesooe lon * 

Cx * Send success message * 

Cx Peewee meer eee ss * 

C MOVEL MSG(4) MSGTEXT 

C EXSR SNDMSG 

C ENDIF 

C* 

C SETON 

Cx* 


LR 


CK KA KKK KKK KKK KKK RE KEK KEK ERK KK EKER KKK EKER KEKE RE RR ERE RE RK RRR ERE 


Cx Subroutine to send a message 
CR K KKK KKK EK KKK KKK KR EKER KER ERK KK RK ERK KR EK RRR EK EKER ERE RE RRR REE 


C SNDMSG 


AIO: OOO: OO 


BEGSR 
CALL 

PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
ENDSR 


Error trying to open FCV file. 
Error reading data from FCV file. 

CSUACFC failed with return/reason codes 9999/9999. 
The Function Control Vector was successfully loaded. 


"QMHSNDPM! 


ERRCODE 


MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 


Example: ILE C program for clearing a function control vector from your 4758 
Coprocessor 
Change this program example to suit your needs for clearing a function control vector from your 4758 
Coprocessor. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
*/ 


Clear the Function Control Vector from the 4758 card. 
The Function Control Vector enables the cryptographic 
functions of the 4758 card. 
disabled the cryptographic functions. 


Clearing it from the 4758 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 2000 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


/* consideration. 


This material contains programming source code for your */ 
These examples have not been thoroughly = */ 


/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or */ 
/* functions of these program. All programs contained x*/ 


/* herein are provided to you "AS IS". 


THE IMPLIED */ 


/* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A x/ 
/* PARTICULAR PURPOSE ARE ARE EXPRESSLY DISCLAIMED. IBM x/ 
/* provides no program services for these programs and files.x/ 


/* 
/* 


*/ 
*/ 


/* Note: Input format is more fully described in Chapter 2 of */ 
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/* IBM 4758 CCA Basic Services Reference and Guide */ 


/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CLEARFCV) */ 
/* */ 
/* x/ 
/* Use the following command to compile this program: */ 
/* CRTCMOD MODULE(CLEARFCV) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CLEARFCV) MODULE(CLEARFCV) x/ 
/* BNDSRVPGM(QCCA/CSUACFC) x/ 
/* */ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* - Cryptographic Facility Control (CSUACFC) x/ 
/* x/ 
[ese Goa Seeesessossasesseeses sa ssee sees esses esesSeseessee Sees */ 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 


void main(void) 
{ 
long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 
long verb_data_length; 
char *verb_data; 
char buffer[4]; 


verb_data_length = 0; 
verb_data = buffer; 


rule_array_count = 2; 
memcpy ((char*)rule_array,"ADAPTERICLR-FCV ",16); 


CSUACFC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char*)rule_array, 
&verb_data_length, 
verb_data); 


if (return_code != 0) 
printf("Operation failed: return code %d : reason code %d \n", 
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return_code, reason_code); 
else 
printf("FCV is successfullly cleared\n"); 


} 


Example: ILE RPG program for clearing a function control vector from your 4758 


Coprocessor 
Change this program example to suit your needs for clearing a function control vector from your 4758 


Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKKKK KKK KKK KEK KK KERR KERR KRKK RE ER KERR RR KEK REE RRR KEKE REE RRR 
D* CLEARFCV 

Dx 

D* Clear the Function Control Vector from the 4758 card. 

D* The Function Control Vector enables the cryptographic 

Dx functions of the 4758 card. Clearing it from the 4758 

D* disabled the cryptographic functions. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx 

D* Parameters: None 

Dx« 

D* Example: 

D* CALL PGM(CLEARFCV) 

Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CLEARFCV) SRCFILE(SAMPLE) 
D* CRTPGM PGM(CLEARFCV) MODULE (CLEARFCV) 


D« BNDSRVPGM(QCCA/CSUACFC) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


Dx 

DA KRKKKKKKK KK KEK KKK ERK KK ERK KERR KERR KER KER RRR RE KR ER KERR ERK ER ERR RRRRER 
DkeeSeeee eee eee ete eee see eee ee eee ee ee eee 
D* Declare variables used on CCA SAPI calls 

Deere SaaS Se-oSs es oaeaoee a aaa a ae ae = Sa Se = = 
Dx *x Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
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DRULEARRAYCNT S 9B 0 


Dx ** Rule array 
DRULEARRAY S 16 

Dx ** Verb data length 
DVERBDATALEN S 9B 0 
Dx «x Verb data 
DVERBDATA S 16 

Dx« 

Dx« 


DA KRRKKKKK KK KER KKK EK KKK ERK KKK ERK KEKE RK KKK KKK KER KEK KER KEKE KEK 


D* Prototype for Cryptographic_Facilty_Control (CSUACFQ) 


DAKAR KKKKKK KK ERK KKK KKK KERR KKK ERK KERR ERE RRR RRR ERK ER KER REE 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 10 

Dx 

Dkereaa aaa — asa SSeS sesso S ae a= See ae a Sa Se ae ee se ee = ee 
Dx *x Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Peaseleesese ees cseee Sas eee eee eee eee cee See eee eee ceetree ee Soe 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 4l 44 

DFAILRSNC 46 49 

Dx ** Variables required for the QMHSNDPM API 
DMESSAGEID S 7 INZ(' ') 
DMESSAGEFTLE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ") 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR K KK KKK KKK KK KKK KR KK ERK KEK ERE KKK KERR KK EK KERR EKER KERR ERE KERR ERR RRE 
Cx START OF PROGRAM * 
Cx * 
CxSeseccsocteccsceeu cece ssssessessoceSsSessscsSosis ssl sseeeees * 
Cx Set the keyword in the rule array * 
CkttececeseSeseese eters eee eke eee esc sooo cee cee eee * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "CLR-FCV ' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

(es ee et * 
Cx Set the verb data length to 0 * 
a a ee ee ee ee * 
C Z-ADD 0 VERBDATALEN 
GksceeeceecSeccecececscescccesSeseoseesSoscsecscesse sss secseees * 
Cx Call Cryptographic Facilty Control SAPI 

Cxkseeese lees cies nce eee eee ee este cece ce cee see seecesoesce * 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

Cc RULEARRAYCNT : 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 
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Ckesessseresseeenceececes * 

C RETURNCODE IFGT 0 

Cx oes acessssessoosees sees * 

Cx * Send a failure message * 

Cx Feeseesessesesesee sete eS * 

C MOVE MSG (1) MSGTEXT 
C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 

Cx* 

C ELSE 

Cx« tos scceeeseSoosecsccoease * 

Cx * Send a Success message * 

Cx* feces eee eee eee eS * 

C MOVE MSG (2) MSGTEXT 
C EXSR SNDMSG 

Cx« 

C ENDIF 

Cx* 

C SETON LR 
Cx« 


CR K KA KKK KKK KKK KKK RE KEK KEK ERK KK EKER KKK EKER KEK ERK RR ERE RRR ERR ERE 


Cx Subroutine to send a message 
CR KKK KK KKK KKK KEKE KR ERE RK ER ERE KK RK ERK RRR EER EKER KERR ERE RK RERERRE ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


** 


CSUACFC failed with return/reason codes 9999/9999' 
The request completed successfully 


Load and set a master key 
After|“Load a function control vector’ on page 73} you can load and set a master key. The 4758 


Coprocessor uses the master key to encrypt all operational keys. The master key is a special 
key-encrypting key stored in the clear (not encrypted) within the 4758 Coprocessor secure module. Your 
4758 Coprocessor uses the master key to encrypt other keys so that you can store those keys outside of 
your 4758 Coprocessor. The master key is a 168—bit key formed from at least two 168-bit parts exclusive 
ORed together. 


Loading a master key 


There are three registers for your master keys: New, Current, and Old. The new master key register is 
used to hold a pending master key while it is being built. It is not used to encrypt any keys. The Current 
master key register holds the master key that is currently being used to encrypt newly 
generated/imported/re-enciphered keys. The old master key register holds the previous master key. It is 
used to recover keys after a master key change has occurred. When you load a master key, the 4758 
Coprocessor places it into the New master key register. It remains there until you set the master key. 


Choose one of these three ways to create and load a master key, based on your security needs: 
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* Load the first key parts and the subsequent key parts separately to maintain split knowledge of the key 
as a whole. This is the least secure method, but you can increase security by giving each key part to a 
separate individual. 


¢ Use random key generation, which will remove any human knowledge of the key. This is the most 
secure method for loading a master key, but you will need to clone this randomly generated master key 
into a second 4758 Coprocessor in order to have a copy of it. 


e Use a pre-existing master key by cloning it from another Coprocessor. 


For more information on cloning master keys, see 
http://www.ibm.com/security/cryptocards/html/library.shtml ad 


Setting a master key 


Setting the master key causes the key in the Current master key register to move to the Old master key 
register. Then, the master key in the New master key register moves to the Current master key register. 


Note: It is vital for retrieval of data encrypted by the master key that you have a backup copy of the 
master key at all times. For example write it on a piece of paper, and make sure that you store the 
backup copy with appropriate security precautions. Or, clone the master key to another 
Coprocessor. 


The easiest and fastest way to load and set master keys is to use the 4758 Cryptographic Coprocessor 
configuration web-based utility found off of the iSeries Tasks page at http://server-name:2001. The utility 
includes the Basic configuration wizard that is used when the Coprocessor is in an uninitialized state. If the 
4758 Coprocessor already has been initialized, then click on Manage configuration and then click on 
Master keys to load and set master keys. 


If you would prefer to write your own application to load and set master keys, you can do so by using the 
Master_Key_Process (CSNBMKP) API verb. Two example programs are provided for your consideration. 
One of them is written in ILE C, while the other is written in ILE RPG. Both perform the same function. 


¢ |“Example: ILE C program for loading a master key into your 4758 Coprocessor’” on page 87 
* |“Example: ILE RPG program for loading a master key into your 4758 Coprocessor’ on page 89 


Note: If you choose to use one of the program examples provided, change it to suit your specific needs. 
For security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Re-encrypting keys 


When you set a master key, you should re-encrypt all keys that were encrypted under the former master 
key to avoid losing access to them. You must do this before you change and set the master key. 


You can re-encrypt keys in key store by using the 4758 Cryptographic Coprocessor configuration 
web-based utility found off of the iSeries Tasks page at http://server-name:2001. The 4758 Coprocessor 
must have already been initialized. Click on "Manage configuration” and then click on either "DES keys” to 
re-encrypt DES keys, or "PKA keys” to re-encrypt PKA keys. 


If you have keys that are not in key store or if you would prefer to write your own application to re-encrypt 
keys, you can do so by using the Key_Token_Change (CSNBKTC) or PKA_Key_Token_Change 
(CSNDKTC) API verbs. An example program is provided for your consideration. 


¢ |“Example: ILE C program for re-encrypting keys for your 4758 Coprocessor” on page 92 
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Note: If you choose to use the program example provided, change it to suit your specific needs. For 
security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Example: ILE C program for loading a master key into your 4758 Coprocessor 
Change this program example to suit your needs for loading a new master key into your 4758 
Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


| ee ee a ee et */ 
/* Load a new master key on the 4758 card. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1, 5722-SS1 (C) IBM CORP. 1999, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function x/ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* x/ 
/* Parameters: x/ 
/* OPTION (FIRST, MIDDLE, LAST, CLEAR, SET) */ 
/* — KEYPART (24 bytes entered in hex -> X'Q1F7C4....') */ 
/* Required for FIRST, MIDDLE, and LAST */ 
/* x/ 
/* Example: */ 
/* CALL PGM(LOAD_KM) */ 
/* (FIRST X'0123456789ABCDEFFEDCBA98765432100123456789ABCDEF')  */ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(LOAD_KM) SRCFILE (SAMPLE) */ 
/* CRTPGM PGM(LOAD_KM) MODULE(LOAD_KM) */ 
/* BNDSRVPGM(QCCA/CSNBMKP QCCA/CSNBRNG) x/ 
/* x/ 
/* Note: Authority to the CSNBMKP and CSNBRNG service programs x/ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* The main Common Cryptographic Architecture (CCA) verb used */ 
/* is Master_Key Process (CSNBMKP) . x/ 
/* x/ 
[Ree eeeeaeeeres leases seaee seco es see se eee eeee soe e see ae eee see oe soe */ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 

/* Service Provider for iSeries */ 


#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


Chapter 5. 4758 Cryptographic Coprocessor for iSeries 87 


/* standard return codes */ 


Sree ene ee eR te eee clei eel eicichaieenieuei */ 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 
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|[Rweosscseasesscses sosseessesseet sess ssase Secs Sse Ssesseacesseasssses 
long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 

char exit_data[4]; 

char rule_array[2] [8]; 

long rule_array_count = 1; 


printf("Option parameter must be specified.\n"); 
return(ERROR) ; 
} 


if (argc < 3 && memcmp(argv[1],"CLEAR",5) != 0 && 
memcmp(argv[1],"SET",3) != 0) 
{ 


printf("KeyPart parameter must be specified.\n"); 
return(ERROR) ; 


memset (rule_array,' ',8); 
memcpy (rule_array,argv[1], 
(strlen(argv[1]) > 8) ? 8: strlen(argv[1])); 


CSNBMKP( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char *)rule_array, 
(argc == 3) ? argv[2] : keypart); 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 


printf ("Request was successful with return/reason codes: %d/%d \n", 
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*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
x/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 


ret 


} 


else 


{ 


pri 


ret 


} 
} 


return_code, reason_code); 
urn(OK) ; 


ntf("Request failed with return/reason codes: %d/%d \n", 
return_code, reason code); 
urn(ERROR) ; 


Example: ILE RPG program for loading a master key into your 4758 Coprocessor 


Change 


this program example to suit your needs for loading a new master key into your 4758 


Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


D«x« 
Dx 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx 
Dx 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx« 
Dx« 
Dx« 
Dx 
Dx« 
Dx 
Dx« 
Dx 
Dx 
Dx« 
Dx« 
Dx« 


KKKKKKKKKEKKKE KEKE EKER KERR KERR KERR KERR KERR KERR KERR KKK EKER RRRRRRRRRERE 


LOAD_KM 


Load a new master key on the 4758 card. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: 
OPTION (FIRST, MIDDLE, LAST, CLEAR, SET) 
KEY PART (24 bytes entered in hex -> X'Q1F7C4....') 
Required for FIRST, MIDDLE, and LAST 


The master key is loaded in 3 or more parts. Specify FIRST 
when loading the first part, MIDDLE when loading all parts 
between the first and the last, and LAST when loading the final 
part of the master key. 


As the master key parts are entered, they are Exclusively OR'ed 
with the current contents of the master key register. After the 
last master key, if the contents do not have odd parity in every 
byte, a non-zero return/reason code will be returned. In order 

to ensure that the final result has odd parity, each key part 
should have odd parity in every byte. This is assuming that there 
is an odd number of key parts. (If there is an even number of 

key parts, then one of the key parts should have even parity). 


A byte has odd parity if is contains: 
an odd parity nibble: 1, 2, 4, 7, 8, B, D, or E AND 
an even parity nibble: 0, 3, 5, 6, 9, A, C, or F. 
For example 32, A4, 1F, and 75 are odd parity bytes because 
they contain both an odd parity and an even parity 
nibble. 
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Dx 


D* 05, 12, 6C, and E7 are even parity bytes because 
Dx they contain either two even parity nibbles or 
D* two odd parity nibbles. 

Dx 


D* The New master key register must be empty before the first part 
Dx of a master key can be entered. Use CLEAR to ensure that the 

D* New master key register is empty before loading the master key 

D* parts. 

Dx 

Dx After loading the master key, use SET to move the master key from 
Dx the New-master-key register to the Current-master-key register. 
D* Cryptographic keys are encrypted under the master key in the 

Dx the Current-master-key register. 


Dx 

D* Example: 

D* CALL PGM(LOAD_KM) (CLEAR) 
Dx« 


D* CALL PGM(LOAD_KM) 
Dx (FIRST X'0123456789ABCDEFFEDCBA98765432100123456789ABCDEF ' ) 
Dx« 
D* CALL PGM(LOAD_KM) 
Dx (MIDDLE X'1032A873458010F7EF3438373132F1F2F4F8B3CDCDCDCEF1' ) 
Dx 
D* CALL PGM(LOAD_KM) 
Dx (LAST X'2040806789ABCDEFFEDC3434346432100123456789FEDCBA' ) 
Dx« 
D* CALL PGM(LOAD_KM) (SET) 

Dx« 

Dx« 

Dx 

Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(LOAD_KM) SRCFILE (SAMPLE) 

D* CRTPGM PGM(LOAD_KM) MODULE(LOAD_KM) 


Dx BNDSRVPGM(QCCA/CSNBMKP) 

Dx 

D* Note: Authority to the CSNBMKP service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Master_Key Process (CSNBMKP) 


Dx 

DARK RK KKK KKK KER KKK KKK KK ERK KKK ERK KK RRR KEKE KKK KER KEK RRR KEK RRR RERKERERE 
D¥eSeeSsesceosccssscossosscscsscosceseeseScossseesscoss 

Dx Declare variables for CCA SAPI calls 

Peeceeee cS sees steece Sas eee ee See ee eee eee eee 

Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN S 9B 0 

Dx xx Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D« xx Qption (Rule Array Keyword) 

DOPTION S 8 

Dx *x Master key part parameter on program 
DMASTERKEY PART S 24 

Dx xx Master key part parameter on CSNBMKP 
DKEYPART S 24 INZ(*ALLX'00') 

Dx« 


DA KRAKK KKK KKK ERK KK KEK KKK ERK KKK KERR KK RRR KKK KKK REE KEK ER KK KERR KEK 


D* Prototype for Master_Key Process (CSNBMKP) 
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DA KRKKKKKK KKK KK KKK EK KKK ERK KKK KKK KER KEK KERR KKK KER KEK RRR KK RRR ER 


DCSNBMKP PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DMSTRKEY 24 OPTIONS (*NOPASS) 

Dx« 
DP¥seseeeossasisesecesceS ose es SoscecscoeesicseesecseossoseSSsasssels 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Dxeeeseeea sos Scee ces ctesscs ce SssceceseosesseSecee SSeS ce ose ssecce 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT il 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO -) 
DSTACKENTRY S 10 INZ('* ry) 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B © INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR KKK KKK KEK KKK KKK KR EKER KER ERK KK EKER KERR ERR EKER ERR KEKE ERR EKER 
Cx START OF PROGRAM * 
Cx* * 
C *ENTRY PLIST 

C PARM OPTION 

C PARM MASTERKEY PART 

Cx* * 
CeeSseSsSsseese sass ssesSa==—Sseaseosese= ao — = Sa S= = Se = —= eS s= * 
Cx Set the keyword in the rule array * 
CkSSsSsetoaee ses eese ese co ee see es Sees eee eae eee * 
C MOVEL OPTION RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

Cx« 
CxsesteScessecsestescecssessossosessossecss-Ssesssceosssssesceee * 
Cx Check for FIRST, MIDDLE, or LAST * 
CxkHeSe eee ete eee eee she seeee sche eens See eee eee ce Se ee * 
C OPTION IFEQ "FIRST! 

C OPTION OREQ "MIDDLE' 

¢ OPTION OREQ "LAST' 

Cx* es aa a a a, co ak car * 

Cx * Copy keypart parameter * 

Cx« fscicacank scceccessseea Sea * 

C MOVEL MASTERKEYPART KEYPART 

C ENDIF 

Cx« 

(CXelseSceeseese seals sel SasSsseS ses -— a= S=5 sees * 

Cx Call Master Key Process SAPI * 
Cxessassessessesossa Sasa —ss—sseosessssoeseesesc5 * 

C CALLP CSNBMKP (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C KEYPART) 
Ckeeeseeeeeseesessseeecccs * 


Cx Check the return code * 
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C RETURNCODE IFGT 0 

Cx Pesseeneeeesececsee cess * 

Cx * Send error message * 

Cx« Kose see scesesecccensces * 

C MOVE MSG(1) MSGTEXT 
C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 

Cx« 

C ELSE 

Cx Se i a iS a ca Sa i i a i * 

Cx * Send success message * 

Cx« twssscasevansceccecesoss * 

C MOVE MSG (2) MSGTEXT 
C EXSR SNDMSG 

Cx 

C ENDIF 

Cx« 

C SETON 

Cx 


CARR KKK KEKE KKK KEK KER EKER KEK ER KEK KEKE KR EKER RRR ERE RARER ERR ER EKER 


Cx Subroutine to send a message 
CX KKK KKK KKK KK KKK KKK KEK KKK EK KE KK EKER KER ERK KER ERE RK RK ERR ER ERERA 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx 


** 


CSNBMKP failed with return/reason codes 9999/9999 
The request completed successfully 


LR 


KKK 


KKK 


Example: ILE C program for re-encrypting keys for your 4758 Coprocessor 
Change this program example to suit your needs for re-encrypting keys for your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
*/ 


eoseecscsssesocesaseessewecsscsceseesnesssoseeseeesessessesseass 
/* Description: Re-enciphers key store files using the current 
/* master key. 

/* 

/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* 


/* This material contains programming source code for your 

/* consideration. These examples have not been thoroughly 

/* tested under all conditions. IBM, therefore, cannot 

/* guarantee or imply reliability, serviceability, or function 
/* of these programs. All programs contained herein are 

/* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for 
/* these programs and files. 

/* 

/* Parameters: 

/* char * keysto_type, choices are "DES" or "PKA" 

/* (If omitted, the default is "PKA".) 
/* Examples: 

/* CALL PGM(REN_KEYSTO) PARM(DES) 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 
#i 
#i 
#i 


/* 
#d 
#d 


in 


in 


{ 


#d 
#d 


CALL PGM(REN_KEYSTO) «/ 


x/ 
Note: The CCA verbs used in the this program are more fully  */ 
described in the IBM 4758 CCA Basic Services Reference */ 
and Guide (SC31-8609) publication. x/ 
*/ 
Note: This program assumes the card you want to use is x/ 
already identified either by defaulting to the CRPO1 */ 
device or has been explicitly named using the */ 
Cryptographic_Resource_ Allocate verb. Also this x/ 
device must be varied on and you must be authorized */ 
to use this device description. x*/ 
x/ 
This program also assumes the key store file you will */ 
use is already identified either by being specified on */ 
the cryptographic device or has been explicitly named = */ 
using the Key_Store Designate verb. Also you must be x/ 
authorized to update records in this file. x/ 
*/ 
Use the following commands to compile this program: */ 
ADDLIBLE LIB(QCCA) x/ 
CRTCMOD MODULE(REN_KEYSTO) SRCFILE (SAMPLE) x/ 
CRTPGM PGM(REN_KEYSTO) MODULE(REN_KEYSTO) x/ 
BNDSRVPGM(QCCA/CSNBKTC QCCA/CSNBKRL */ 
QCCA/CSNDKTC QCCA/CSNDKRL) x/ 
x/ 
Note: authority to the CSNDKTC, CSNDKRL, CSNBKTC, and CSNBKRL */ 
service programs in the QCCA library is assumed. x/ 
*/ 
Common Cryptographic Architecture (CCA) verbs used: x/ 
PKA_Key_Token_Change (CSNDKTC) x/ 
DES_Key_Token_ Change (CSNBKTC) */ 
PKA_Key_Record_List (CSNDKRL) */ 
DES Key Record List (CSNBKRL) */ 
ee */ 
nclude <stdlib.h> 
nclude <stdio.h> 
nclude <string.h> 
nclude "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 
Define the acceptable file types */ 
efine PKA 1 
efine DES 0 
t re_encipher(FILE *key_rec, long rec_length, int key_type); 
t main(int argc, char «argv[]) 
| Reeeeeeenecedeasen sens aeas aoe =aacesesser eee es=esa=ssceseseee */ 
/* standard return codes x/ 
[#eseesteieon tones sec ssceseera lessees eee setae oth eeeces */ 
efine ERROR -1 
efine OK 0 
| Raeeeeeereseasaseassmaeeces=sseS—-SS> Ses ese—esesseseseeseae */ 
/* standard CCA parameters x/ 
| ee ee ee */ 


long return_code = 0; 
long reason_code = Q; 
long exit_data_length = 0; 
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char exit_data[2]; 
long rule_array_count = 0; 
char rule_array[1] [8]; 


[kaa see aes cease seo seese see eso ease sees aes Seo> Se oe= = ee */ 
/* fields unique to this sample program */ 
[xeSesscesseee se ses soe ese eee eee sce Seseesnasasesseese = */ 


char key_label[65] = 
"Wk KKK LK KK 
long data_set_name_length = 0; 
char data_set_name[65]; 
char security_server_name[9] = " vig 


FILE *kr1; 

int keysto_type = PKA; 

[Paseeeese sates cese eee eeeeaet asec see eee eee cess Sceee */ 
/* Check whether the user requested to re-encipher a DES or */ 
/* a PKA keystore file. Default to PKA if key file type is */ 


/* not specified. i 
| A A RE EE EEE eee eee ee ere see ae are “ 
if (argc >= 2) 
{ 
if ((strcemp(argv[1],"DES")==0) ) 
{ 
printf("\nDES "); 
keysto_type = DES; 
} 


else if ((strcmp(argv[1] ,"PKA")==0) ) 
printf("\nPKA "); 

else 

{ 
printf("\nKeystore type parm incorrectly specified.\n"); 
printf ("Acceptable choices are PKA or DES.\n"); 
printf("The default is PKA.\n"); 
return ERROR; 


} 


else 


{ 
printf("\nPKA "); 


if (keysto_type == DES) 


{ 
[Rese s ese se ceeee sete see ese eee ee cee See Se eeeee se eee aces */ 
/* Invoke the verb to create a DES Key Record List */ 
[Peeneeers sees =sasnsee secs eee edsee se ese = soeseersees asses —2-== */ 


CSNBKRL( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_label, 
&data_set_name_length, 
data_set_name, 
security_server_name) ; 


} 

else 

{ 
| ee ee eee a */ 
/* Invoke the verb to create a PKA Key Record List x/ 
| ee ee ee ee */ 


CSNDKRL( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
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(char *) rule_array, 
key_label, 
&data_set_name_length, 
data_set_name, 
security_server_name) ; 


} 


if ((return_code != 0) || (reason_code != 0)) 


printf("Key Record List generation was unsuccessful. "); 
printf ("Return/reason code = %d/%d\n",return_code, reason_code); 


} 


else 


printf("Key Record List generation was successful. "); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
data_set_name[data_set_name_length] = '\0'; 

printf ("data_set_name = %s\n",data_set_name) ; 


/* Open the Key Record List file. */ 
kr1 = fopen(data_set_name, "rb"); 


if (kr] == NULL) /* Open failed. */ 
{ 
printf("The open of the Key Record List file failed\n"); 
return ERROR; 
} 
else /* Open was successful. */ 
{ 
char header1[77]; 
int num_rec, i; 
long rec_length, offset_recl; 


/* Read the first part of the KRL header. */ 
fread(headerl,1,77,kr1); 


/* Get the number of key records in the file. */ 
num_rec = atoi(&header1[50]); 
printf("Number of key records = %d\n",num_rec) ; 


/* Get the length for the key records. */ 
rec_length = atol (&header1[58] ); 


/* Get the offset for the first key record. */ 
offset_recl = atol (&header1[62]); 


/* Set the file pointer to the first key record. */ 
fseek(kr1, offset_recl, SEEK_SET); 


/* Loop through the entries in the KRL and re-encipher. */ 
for (i = 1; i <= num_rec; i++) 
{ 
int result; 
result = re_encipher(kr1, rec_length, keysto_type); 
if (result !=0) 
{ 
fclose(kr1); 
return ERROR; 


printf("Key store file re-enciphered successfully.\n\n"); 
fclose(kr1); 
return OK; 
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} /* end of main() */ 


int re_encipher(FILE *key_rec, long rec_length, int key_type) 
{ 


[xesssseesssssoseseseneeeee seen as SSeS Soles */ 
/* standard CCA parameters x/ 
[#seceesewescssesensesssesssseessessss Se sSeese cesses Seeee */ 


long return_code; 
long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count 
char rule_array[1] [8]; 


iT} 
oO 


iT 
RR 
we 


long key_identifier_length = 64; 
char key_identifier[64]; 
char key_record[154]; 


fread(key_record, 1, rec_length, key_rec); 
memcpy(key_identifier, &key_record[3], 64); 
memcpy(rule_array, "RTCMK ",8); 


if (key_type == DES) 
{ 
CSNBKTC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_identifier); 


} 
else if (key_type == PKA) 


CSNDKTC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
&key_identifier_length, 
key_identifier); 
} 
else 
{ 
printf("re_encipher() called with an invalid key type.\n"); 
return ERROR; 
} 
printf("Re-enciphering for key_label = %.64s",key_ identifier) ; 
printf("completed with return/reason codes of "); 
printf ("%d/%d\n", return_code, reason_code) ; 
return return_code; 


}/* end of re_encipher() */ 
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Configure the 4758 Cryptographic Coprocessor for use with DCM and 
SSL 


The following section lists the steps needed to make the 4758-023 Coprocessor ready for use with SSL. 
Using your 4758-023 Coprocessor with DCM and SSL 


To install the 4758-023 Coprocessor and prerequisite software, you must do the following: 
¢ Install the Coprocessor in your server. 


For feature 4801, install your 4758-023 Coprocessor, as instructed in the 4801 PCI Cryptographic 
Coprocessor Card Instructions that are shipped with your 4758-023 Coprocessor. 


For feature 4802, ask your IBM hardware service representative to install your 4758-023 Coprocessor. 
¢ Install OS/400 Option 35 CCA CSP. 
* Install either the 5722—AC3 Cryptographic Access Provider 128-bit licensed program product. 


* Set OS/400 object authorities for|“Secure access to the 4758 Cryptographic Coprocessor” on page 21 


¢ Use your web browser to go to the iSeries Tasks page at http://server-name:2001. 


. ae ure the 4758 by following the steps in|“Configure the 4758 Cryptographic Coprocessor” on 


The 4758-023 Coprocessor is now ready to be used to create private keys for SSL certificates. 
¢ Use DCM to create a certificate, specifying that the private key be generated by the hardware. 
¢ Use DCM to receive the signed certificate. 


See|Manage public Internet certificates for SSL communications sessions}for more information on these 


last two steps. 


Note: If you plan to use multiple cards for SSL, see|“Manage multiple 4758 Cryptographic Coprocessors” 
ion page 179}and/|“Clone master keys” on page 189 


Configure the 4758 Cryptographic Coprocessor for use with OS/400 
applications 
The following section lists the steps needed to make the 4758-023 Coprocessors ready for use with a 


OS/400 application. See|Cryptographic hardware scenario: Write an OS/400 application to use the 4758 
Cryptographic Coprocessor|for an example usage of the 4758 Cryptographic Coprocessor in an OS/400 
application. 


Using the 4758-023 Coprocessor for OS/400 applications 


To install the 4758 Coprocessor and prerequisite software, you must do the following: 
* Install the Coprocessor in your server. 


For feature 4801, install your 4758 Coprocessor, as instructed in the 4801 PCI Cryptographic 
Coprocessor Card Instructions that are shipped with your 4758 Coprocessor. 


For feature 4802, ask your IBM hardware service representative to install your 4758 Coprocessor. 
¢ Install OS/400 Option 35 CCA CSP. 


* Install either the 5722—AC3 Cryptographic Access Provider 128-bit or the 5722—AC2 Cryptographic 
Access Provider 56-bit licensed program product. 


* Set OS/400 object authorities for|“Secure access to the 4758 Cryptographic Coprocessor” on page 21 


e Use your web browser to go to the iSeries Tasks page at http://server-name:2001. 


* Configure the 4758 by following the steps in|“Configure the 4758 Cryptographic Coprocessor’” on 
page 23] 23 


¢ Write your application to use the Cryptographic Coprocessor. 
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If you plan to use multiple cards for your OS/400 applications, see |“Manage multiple 4758 


Cryptographic Coprocessors” on page 179 


Note: 


| 


Migrate to the 4758 Cryptographic Coprocessor 


This information explains how to perform the following migrations: 


¢ |Migrate from other iSeries cryptographic products to the 4758 Cryptographic Coprocessor 
¢ |Migrate key store files 


Migrate from other iSeries cryptographic products to the 4758 
Cryptographic Coprocessor 


If you have worked with cryptography before, you may have one of two cryptographic products on your 
server. You may have key store files from the IBM CCA Services for iSeries (5799-FRF) product. Or, you 
may have cryptographic cross-domain files from Cryptographic Support for iSeries (5769-CR1). If this is 
the case, you can migrate their contents to your new 4758 Coprocessor. There is an example migration 
program available for each cryptographic product: 


¢ IBM CCA Services for iSeries (5799-FRF). This product provides cryptographic function on 
cryptographic hardware by using Data Encryption Standard (DES). The Common Cryptographic 
Architecture (CCA) Services requires that you have a cryptographic processor, feature number 2620 or 
2628, installed on your server. You can migrate key store files from the IBM CCA Services to your 4758 


Coprocessor using |“Migrate key store files from the IBM CCA Services for iSeries” 


Cryptographic Support for iSeries (5769—CR1 or 5722—CR1). Cryptographic Support is a 
software-only product that encrypts cross-domain keys under a host master key. Cryptographic Support 
then stores the cross-domain keys in a file. You can migrate cross-domain key files from Cryptographic 


Support for iSeries server to your 4758 Coprocessor using|“Migrating Cryptographic Support for iSeries 
cross-domain key files” on page 108 


Migrate key store files from the IBM CCA Services for iSeries 

If you currently use the Common Cryptographic Architecture (CCA) Services for iSeries (5799-FRF), you 
can migrate the keys in the key store file so that your 4758 Coprocessor can use them. The Coprocessor 
uses the migrated keys with the CCA Cryptographic Service Provider (CCA CSP, which is packaged as 
OS/400 Option 35). 


) 


Note: You cannot migrate all keys because the CCA Services supports a wider range of key types than 
the 4758 Coprocessor. For example, you cannot migrate keys that have had the prohibit-export bit 
in the control vector set. Also, you cannot migrate any of the PKA keys in the CCA Services for 
iSeries because CCA Services provides public key algorithm (PKA) support that is significantly 
different than that in the 4758 Coprocessor. 


You will need to write two programs to migrate your Data Encryption Standard (DES) keys. Or, there are 
lwo program examples, fExampe: EXPORTIng keys" on page 9] and Example: IMPORTTng Keys" o 
which you can change and run to migrate the key store files. The CCA defines the format of the 
external DES key tokens and therefore is the same for both products. 


Use the EXPORT program in conjunction with the IMPORT program. This will migrate DES keys from the 
IBM CCA Services for iSeries to your 4758 Coprocessor and CCA CSP. You should run the EXPORT 
program first to generate a file that contains the necessary key information in a secure, exportable form. 
You should then transfer the file to the target server. You can then run the IMPORT program to import the 
keys from the file into a key storage file that you have created. The key storage file to which you want to 
import the keys must already exist before you run the program. 


To change the program examples, follow these steps. 


1. Import the same clear key value for a key-encrypting key into both products. For the CCA Services, the 
key-encrypting key must be an EXPORTER, and for CCA CSP it must be an IMPORTER. 
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Run the Key_Export (CSNBKEX) CCA API in the CCA Services for each key you want to migrate. This 


causes the program example to call an API. 


Import the outputted external key token into CCA CSP and your 4758 Coprocessor by using the 
Key_Import (CSNBKIM) CCA API. Remember to change the program to do this for each key. 


Once you change the program to address each key, you can run the program. Remember to run EXPORT 
first and then IMPORT. 


Note: If you choose to use the program examples provided, change them to suit your specific needs. For 


Example: EXPORTing keys: This is step one. Change this 
migrating the key store files. Once you run this program, use 


security reasons, IBM recommends that you individualize these program examples rather than 


program example to suit your needs for 
“Example: IMPORTing keys” on page 104] to 


using the default values provided. 


complete the migration process. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 


Description: One of two programs used to migrate DES keys 
from a key store file used with the 2620 to a 
key store file for use with the 4758. 


Note: This program is intended to be used in conjunction with 
IMPORT_TSS to migrate DES keys from 2620 to 4758. 
EXPORT_TSS should be run first to generate a file 
containing the needed key information in a secure, 
exportable form. The file should then be transferred 
to the target system. IMPORT_TSS can then be run using 
the file to import the keys into a previously created 
key storage file. 


COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these programs. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Parameters: File to contain exported key information 


Examples: 
CALL PGM(EXPORT_TSS) PARM('File_for_Exported_Keys') 


Use the following commands to compile this program: 
ADDLIBLE LIB(QTSS) 
CRTCMOD MODULE(EXPORT_TSS) SRCFILE(SAMPLE) 
CRTPGM PGM(EXPORT_TSS) MODULE(EXPORT_TSS) 


Note: authority to the functions CSNBKEX, CSNBKPI, CSNBKRL, 
and CSNBKTB is assumed 
Common Cryptographic Architecture (CCA) verbs used: 
Key_Export CSNBKEX 
Key_Part_Import CSNBKPI 
Key_Record List CSNBKRL 
Key_Token_Build CSNBKTB 


nclude <stdlib.h> 
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#include <stdio.h> 
#include <string.h> 


#include "MIPTRNAM.H" /* needed to resolve function ptrs */ 
#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 


int main(int argc, char *argv[]) 


{ 
| $e cece scesecsecss sete seetass ssh os see sees ssessesoss */ 
/* standard return codes x/ 
[hosesesees she eseses ce senseceeHe snes Seeseeecesescas «/ 


#define ERROR -1 
#define OK 0 


| ee ee ee et */ 
/* Declare function pointers (see csucincl.h) */ 
/ Pace tuscessaessasecsesse sss sass ses sacssssecHseosas */ 


T_CSNBKEX *CSNBKEX; 
T_CSNBKRL *CSNBKRL; 
T_CSNBKPI *CSNBKPI; 
T_CSNBKTB *CSNBKTB; 


| eesececsssecsesseesee seas eee dees Se cesses ees «/ 
/* standard CCA parameters x/ 
[ #escate mes eesseessossesssecse=seaas=cssesecsceesase */ 


long return_code; 
long reason_code; 


long exit_data_length = 0; 

char exit_data[2]; 

long rule_array_count = 0; 

char rule_array[2] [8]; 

[Rose aseacseeeaosemaceesneeees sso seaeseseseeeccnse a= «/ 
/* additional parameters needed for CSNBKRL */ 
/#asectecesascssadsdsesasesssscssesssessesseanse=ss5 */ 


char key_label [64]; 
long data_set_name_length = 0; 
char data_set_name[65]; 


char security_server_name[9] = " ms 

[Roses teeesnaes shee eceeenseressssnessatesneeoceesess */ 
/* additional parameters needed for CSNBKEX */ 
J Peseekencsscsacascssutsesecsseescesssesssssesesslss */ 


char key_type[8]; 

char source_key_identifier[64]; 
char exporter_key_identifier[64]; 
char target_key_token[64]; 


| $egeeeawes = sesso ses seececeeea=eteesecesesecsece=sce */ 
/* additional parameters needed for CSNBKTB */ 
[esas secssseeapeect ease haseossaceesececeeeerste ea */ 


char key_token[64] ; 

char key_value[64]; 

long master_key_verification_pattern = 0; 
long reserved_int; 

char reserved_str[8]; 

char control_vector[16] ; 


0 ee eee eee «/ 
/* additional parameters needed for CSNBKPI */ 
[heee eee soa e ease eee sees naseeasaosesaseecesstasesese «/ 


char key_part[16]; 
char key_identifier[64]; 
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char header1[77]; 

long num_rec, i; 

long num_successful = 0; 

long rec_length, offset_recl; 


char key_record[154]; 


FILE *krl, *export_file; 


/* Check input parm */ 

if (arge < 2) 

{ 
printf("File for storing the exported key data not specified.\n"); 
return ERROR; 


} 

| a ee eet */ 
/* Resolve function pointers */ 
JesasessadessesesSseuseesseesssssassscsessssssensese */ 


_lib_quali fy (CSNBKEX,QTSS) 
~1ib_qualify(CSNBKRL,QTSS) 
~1ib_qual ify (CSNBKPI ,QTSS) 
~1ib_qual ify (CSNBKTB,QTSS) 


memset (key_label,' ',64); 
memcpy (key_label,"*.*.*.*.*",9); 


[eeseebSeea secesseue eet ese ese se eases eee eee eee Sees ee case ee */ 
/* Invoke the verb to create a DES Key Record List */ 
 teee eee seaeeesess see seesasees ase ses enese eee as] eeae sas =ceae */ 


CSNBKRL( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_label, 
&data_set_name_length, 
data_set_name, 
security_server_name) ; 


if ((return_code != 0) || (reason_code != @)) 

{ 
printf("Key Record List generation was unsuccessful. "); 
printf("Return/reason code = %d/%d\n",return_code, reason_code); 
return ERROR; 


} 

printf("Key Record List generation was successful. "); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
data_set_name[data_set_name_length] = '\0'; 


printf ("data_set_name = %s\n\n",data_set_name) ; 


/* Generate a clear key for export use. */ 
/* The same key will be used for import. */ 
memcpy (key_type, "EXPORTER",8) ; 
rule_array_count = 2; 

memcpy (rule_array[0],"INTERNAL",8) ; 

memcpy (rule_array[1],"KEY-PART",8); 
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CSNBKTB( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_token, 
key_type, 
&rule_array_count, 
(char *) rule_array, 
key_value, 
&master_key_verification_pattern, 
&reserved_int, 
reserved str, 
control_vector, 
reserved str, 
&reserved_int, 
reserved str, 
reserved str); 


if (return_code != 0) { 
printf("Building of the export key failed.\n"); 
printf("Key Token Build failed."); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
return ERROR; 
} 


/* Import the key parts to be used. */ 
rule_array_count = 1; 
memcpy(rule_array[0],"FIRST ",8); 
memset (key_part,'\x01',16); 


for(i=l;i<=2;it+) { 

CSNBKPI( &return_code, 
&reason_code, 
&exit_data_length, 
(char *) exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_part, 
key_token); 


if (return_code != 0) { 
printf("Building of the export key failed.\n"); 
printf("Key Part Import failed."); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
return ERROR; 


} 
memcpy (rule_array[0] ,"LAST " 8); 
/* Set key part to the clear key to be used. */ 


/* Note: It may not be desirable to hard-code this. */ 
memcpy (key_part,"ClEar.KEY.hErE!!",16); 


} 


/* Export key built successfully. */ 
/* Open the Key Record List file. */ 
kr1 = fopen(data_set_name, "rb"); 


if (kr1 == NULL) 

{ /* Open failed. */ 
printf("The open of the Key Record List file failed.\n"); 
return ERROR; 
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/* Key record list open was successful. */ 
/* Open the file to save key info. x/ 
export_file = fopen(argv[1], "wb"); 
if (export_file == NULL) 
{ 
printf("Opening of key export file failed.\n"); 
fclose(kr1); 
return ERROR; 
} 


/* Write num_successful to the export file to hold a place for it. */ 
fwrite(&num_successful,sizeof(long),1,export_file); 


/* Read the first part of the KRL header. */ 
fread(headerl,1,77,kr1); 


/* Get the number of key records in the file. */ 
num_rec = atoi(&header1[50]); 
printf("Number of key records = %d\n",num_rec); 


/* Get the length for the key records. */ 
rec_length = atol (&header1[58]); 


/* Get the offset for the first key record. */ 
offset_recl = atol (&header1[62]); 


/* Set the file pointer to the first key record. */ 
fseek(krl, offset_recl, SEEK_SET); 


/* Set the key type to TOKEN. */ 
memcpy(key_type,"TOKEN ",8); 


/* Loop through the entries in the KRL and EXPORT. */ 
for (i = 1; i <= num_rec; i++) 
{ 
fread(key_record, 1, rec_length, kr1); 
memcpy(source_key identifier, &key_record[3], 64); 


CSNBKEX(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_type, 
source_key_identifier, 
key_token, 
/* exporter_key_identifier, */ 
target_key_ token); 


printf("Exporting of key = %.64s",source_key_identifier); 
printf("completed with return/reason codes of "); 
printf ("%d/%d\n", return_code, reason_code) ; 


if (return_code == 0) 

{ 
++num_successful ; 
fwrite(source_key_identifier, 1, 64, export_file); 
fwrite(target_key_ token, 1, 64, export_file); 

} 


} /* end of for loop */ 


printf("Key store file exported successfully.\n"); 
printf("%d key(s) successfully exported.\n\n",num successful) ; 


/* Write out the number of exported keys and close the file. */ 


fseek(export_file,0,SEEK_SET); 
fwrite(&num_successful,sizeof(long),1,export_file); 
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/* Close the files and return. */ 
fclose(kr1); 

fclose(export_file); 

return OK; 


} 


Example: IMPORTing keys: This is step two. If you have not already done so, run the 
EXPORTing keys” on page 99] program to begin the migration process. Then change this program example 


to suit your needs for completing the migration of the key store files. 


[Rees eeete ese esas ee sess eee eee faa a sae see sae cee aeeseaes=eeaeasee */ 
/* Description: One of two programs used to migrate DES keys x/ 
/* from a key store file used with the 2620 toa +*/ 
/* key store file for use with the 4758. */ 
/* x/ 
/* Note: This program is intended to be used in conjunction with */ 
/* EXPORT_TSS to migrate DES keys from 2620 to 4758. */ 
/* EXPORT_TSS should be run first to generate a file */ 
/* containing the needed key information in a secure, */ 
/* exportable form. The file should then be transferred */ 
/* to the target system. IMPORT_TSS can then be run using */ 
/* the file to import the keys into a previously created */ 
/* key storage file. x/ 
/* */ 
/* */ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 

/* */ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* */ 
/* Parameters: File containing exported key information x/ 
/* x/ 
/* Examples: x/ 
/* CALL PGM(IMPORT_TSS) PARM('Exported_Key_File') x/ 
/* x/ 
/* Note: The CCA verbs used in the this program are more fully’ */ 
/* described in the IBM 4758 CCA Basic Services Reference */ 
/* and Guide (SC31-8609) publication. */ 
/* */ 
/* Note: This program assumes the card you want to use is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic_Resource_ Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. x/ 
/* x/ 
/* This program also assumes the key store file you will */ 
/* use is already identified either by being specified on */ 
/* the cryptographic device or has been explicitly named */ 
/* using the Key_Store Designate verb. Also you must be x/ 
/* authorized to update records in this file. x/ 
/* x/ 
/* Use the following commands to compile this program: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(IMPORT_TSS) SRCFILE (SAMPLE) */ 
/* CRTPGM PGM(IMPORT_TSS) MODULE(IMPORT_TSS) x/ 
/* BNDSRVPGM(QCCA/CSNBKRC QCCA/CSNBKIM QCCA/CSNBKPI)  */ 
/* x/ 
/* Note: authority to the CSNBKIM, CSNBKPI, and CSNBKRC */ 
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/* service programs in the QCCA library is assumed. x/ 


/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* — Key_Import CSNBKIM */ 
/* Key _Record_Create CSNBKRC x/ 
/* Key_Part_Import CSNBKPI */ 
[#eseessesseasassesn sees oes ones Soe soe seeeee ee eee ena ce sae eceee se */ 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 
| ee eee ee ee eee eee eee */ 
/* Structure defining the DES key token for internal keys. This */ 
/* structure is used in the creation of the importer key- */ 


/* encrypting key. For more information on the fields in this */ 
/* structure, see the IBM 4758 CCA Basic Services Reference and */ 


/* Guide (SC31-8609-01), Appendix B and C. x*/ 
[ $eocseeee eee eee eee oss ee Sees se seeses eee eae ee eeeteene case See */ 
struct DES_key_token { 
char type; /* Set to 0x01 for ‘internal’ x/ 
char resvl; /* Reserved (set to binary zero) */ 
char mkvp[2]; /* Master Key Verification Pattern */ 
char version; /* Version. Will be set to 0x03. */ 
char resv2; /* Reserved (set to binary zero) */ 
char flag; /* Flag */ 
char resv3; /* Reserved (set to binary zero) x/ 
char resv4[8]; /* Reserved (set to binary zero) */ 
char key1[8]; /* Single length encrypted key or 
left half of double length 
encrypted key. */ 
char key2[8]; /* Null or right half of double 
length encrypted key x/ 
int cvb1[2]; /* Control-vector base x*/ 
int cvb2[2]; /* Null or control vector base for 
the 2nd eight-byte portion of a 
16-byte key */ 
char resv5[12]; /* Reserved (set to binary zero) */ 
int tvv; /* Token-validation value */ 


}3 


int main(int argc, char *argv[]) 


| eee eee */ 
/* standard return codes */ 
[feeeSeeseaeecesessesessesaseecseeeoesesaes aoe eee ae seaee */ 


#define ERROR -1 
#define OK 0 


/#acesseraesee Sse seeessasassesse ee saseesseeeeeSneeceeansesee a] */ 
/* standard CCA parameters x/ 
Jeoseeseesosssssesecnsscasesess-csssese ses sssasessessesssscae */ 


long return_code; 
long reason_code; 


long exit_data_length = 0; 

char exit_data[2]; 

long rule_array_count = 0; 

char rule_array[2] [8]; 

[ee see seca aee a sae aaa ae aoa eae sees seo ee ae ee oes eeeeeses sone */ 


/* additional parameters required for CSNBKRC and CSNBKIM */ 
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char import_key_label [64]; 
char import_key_token[64]; 


 $aceeee esas aeseoaes seecedse saan sacs aesses seo - Se Seeoe soos */ 
/* additional parameters required for CSNBKPI */ 
[Rosca scsscsasSechesedendee secs sce seeseseesecneseassecesces */ 


struct DES_key_token importer_kt; 


char importer_key_token[64] ; 
char key_type[8]; 
char key_part[16]; 


/eesscesaseesessasssssessas-ssoss esses a Seaseesescess «/ 
/* Other variables x/ 
[hoseeeseses ec eeseen se eae esas sads ese ese e Sassen sees «/ 


long num_rec = 0, 7; 
long num_imported = 0; 


FILE *import_file; 


printf("\n\n"); 

/* Check input parm */ 
if (arge < 2) 

{ 


printf("File containing the exported key data not specified.\n"); 
return ERROR; 
} 


/* Generate a clear key for import use. */ 


/* Initialize the importer key token. */ 

memset (&importer_kt,0x00,sizeof(struct DES _key_token)); 
importer_kt.type = 0x01; 

importer_kt.version = 0x03; 

importer_kt.flag = 0x40; /* Indicates control vector is present */ 
importer_kt.cvb1[0] = 0x00427d00; 


importer_kt.cvbl[1] = 0x03480000; 
importer_kt.cvb2[0] = 0x00427d00; 
importer_kt.cvb2[1] = 0x03280000; 


importer_kt.tvv = 0x0af53a00; 


/* Initialize parameters for the first pass */ 
rule_array_count = 1; 
memcpy(rule_array[0],"FIRST  ",8); 

memset (key_part,0x01,16); 


for(i=l;i<=2;it+) { 

CSNBKPI( &return_code, 
&reason_code, 
&exit_data_length, 
(char *) exit_data, 
&rule_array_count, 
(char *) rule_array, 
key_part, 

(char *) &importer_kt); 


if (return_code != 0) { 
printf("Building of the importer key failed.\n"); 
printf("Key Part Import failed."); 
printf("Return/reason codes = %d/%d\n",return_code, reason_code); 
return ERROR; 
} 
else if ( i == 1) { 
/* Init variables for the final pass */ 
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memcpy (rule_array[0], "LAST " 58): 
/* Set key part to the clear key to be used. */ 
memcpy (key_part,"ClEar.KEY.hErE!!",16) ; 
} 
} 


/* Import key built successfully. */ 
printf("Importer key built successfully.\n\n"); 


/* Open the Exported Key file. */ 
import_file = fopen(argv[1], "rb"); 


if (import_file == NULL) 

{ /* Open failed. */ 
printf("The open of the Exported Key file failed\n"); 
return ERROR; 

} 


/* Import Key file open was successful. */ 
fread(&num_rec,sizeof(num_rec),1,import_file); 


/* Loop through the entries in the import file and create key records. */ 
for (i = 1; i <= num_rec; i++) 


{ 


fread(import_key_label, 1, 64, import_file); 
fread(import_key_ token, 1, 64, import_file); 


printf("Importing DES key:\n"); 
printf (" \"%.64s\"\n", import_key_label); 


/* Create a key record. */ 

CSNBKRC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
import_key_label); 


if (return_code != 0) 


{ 
printf (" Key record creation failed. "); 
printf("Return/reason codes = %d/%d\n\n", return_code, reason_code) ; 
continue; 


} 


/* Else, key record created successfully so import the key. */ 
memcpy(key_type,"TOKEN ",8); 


CSNBKIM( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_type, 
import_key_token, 
(char *) &importer_kt, 
import_key_label); 


if (return_code != 0) 


{ 
printf (" Key import failed. "); 
printf ("Return/reason codes = %d/%d\n\n", return_code, reason_code) ; 
continue; 

} 

/* else, Key import was a success. */ 

printf (" Key imported successfully. "); 


printf("Return/reason codes = %d/%d\n\n", return_code, reason_code) ; 
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++num_imported; 
} /* end of for loop */ 


printf("\nCompleted key import procedure.\n"); 

printf("%d of %d key(s) successfully imported.\n\n",num_imported,num_rec) ; 
fclose(import_file); 

return OK; 


} 


Migrating Cryptographic Support for iSeries cross-domain key files 

If you have worked with cryptography before on your server, you may have cryptographic cross-domain 
files from Cryptographic Support for iSeries (56769—CR1). You can migrate existing cross-domain keys to 
your new 4758 Coprocessor. 


The Cryptographic Support for iSeries product (5769—CR1 or 5722-CR1) encrypts its cross-domain keys 
under the host master key and stores them in a file. Common Cryptographic Architecture (CCA) cannot 
use them in this form, but you can migrate them from the Cryptographic Support product for the CCA to 
use with your Coprocessor. You must consider a number of things before completing this task: 


¢ Encryption of cross-domain keys by cross-domain keys. Cryptographic Support for iSeries supports 
importing clear key values for cross-domain keys and encrypting data keys under cross-domain keys. 
However, it does not support encrypting cross-domain keys under cross-domain keys, nor does it 
support returning the clear key value of any cross-domain key. Because of this, migrating cross-domain 
keys is considerably more involved than just performing an export and import operation. 


¢ Single-length keys versus double-length keys. All keys in Cryptographic Support for iSeries are 
single-length keys. In CCA, all key-encrypting keys and PIN keys are double-length keys. Although the 
key lengths are different, you can build a double-length key from a single-length key and have that 
double-length key behave like the single-length key. If both halves of a double-length key are the same, 
the result of any encryption operation will be the same as if a single-length key was used. Therefore, 
when you migrate keys from Cryptographic Support for iSeries to CCA, you will need to copy the key 
value of the cross-domain key into both halves of the key value for a CCA key. 


* CCA control vectors versus master key variants. In CCA, when a key is said to be encrypted under 
a key-encrypting key, it is really encrypted under a key that is formed by an exclusive OR operation of 
the key-encrypting key and a control vector. For Cryptographic Support, cross-domain keys are 
encrypted under one of three different master key variants. A master key variant is the result of the 
exclusive OR operation of the host master key with either 8 bytes of hexadecimal 22, 44, or 88. Both 
control vectors and master key variants provide key separation and thereby restrict keys to their 
intended use. In CCA, the value of the control vector determines its use. In Cryptographic Support how 
a key is used determines which master key variant will be used to decrypt it. In both cases, any attempt 
to use the key for other than its intended use will result in an error. Although control vectors and master 
key variants may work similarly, the values used to form master key variants are not the same as 
control vectors. 


¢ Asymmetry of CCA control vectors for double-length keys. Double-length keys behave like 
single-length keys only when both halves of the double-length key are identical. Control vectors for 
double-length keys are asymmetric. Any double-length key that is exclusive ORed with a control vector 
will not result in a key with identical halves. This double-length key will not behave like a single length 
key. 


You can choose one of two methods for migrating the keys. 
Method 1 (Recommended) 


This method provides some solutions to the considerations listed above and is the recommended method 
to use. 


To migrate the cross-domain keys from Cryptographic Support to CCA, you will need to use a 
key-encrypting key that is common to both. You can use the Cryptographic Support host master key as the 
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common key between Cryptographic Support and CCA (in CCA, the host master key is known as the 
master key). Import the Cryptographic Support host master key clear value into CCA as an IMPORTER 
key-encrypting key. Because you enter the host master key in two separate parts, you should consider 
importing it into CCA as two parts using the Key_Part_Import (CSNBKPI) CCA API. If you had dual 
responsibility for the Cryptographic Support host master key, you should maintain this dual responsibility 
for this key-encrypting key. Alternatively, if you know both parts of the host master key, you could also 
perform an exclusive OR of the two parts and import the key in just one part. The program example uses 
this method of importing the host master key. You may want to consider importing the host master key in a 
completely separate process instead of combining it with the migration of all cross-domain keys like the 
program example does. 


There are three types of cross-domain keys: 
* Receiving cross-domain keys 

¢ Sending cross-domain keys 

¢ PIN cross-domain keys 


The CCA equivalent of receiving cross-domain keys are IMPORTER key-encrypting keys. Both are used 
for receiving or importing an encrypted key. 


Sending-cross-domain keys are used for both a) encrypting data keys, which can then be sent to another 
system, and b) translating encrypted personal identification numbers (PIN). CCA has stricter key 
separation than the Cryptographic Support product, so you cannot generate or import a key that provides 
both functions. If the key is used as both an EXPORTER key-encrypting key and an OPINENC (outbound 
PIN encrypting) key, you need to import sending-cross-domain keys twice into two different keys with two 
different key types. 


You may use PIN-cross-domain keys for generating PINs and verifying PINs. CCA separates these two 
usage’s into PINGEN (PIN generation) and PINVER (PIN verification) keys. If the key is used for both 
generating and verifying PINs, you need to import PIN-cross-domain keys twice as well. 


While the host master key encrypts data keys, different master key variants encrypt cross-domain keys. 

* Master key variant 1 encrypts sending cross-domain keys. Variant 1 is the result of an exclusive-OR 
operation of the host master key with 8 bytes of hexadecimal 88. 

¢ Master key variant 2 encrypts receiving cross-domain keys. Variant 2 is the result of an exclusive-OR 
operation of the host master key and 8 bytes of hexadecimal 22. 

¢ Master key variant 3 encrypts PIN cross-domain keys. Variant 3 is the result of an exclusive-OR 
operation of the host master key and 8 bytes of hexadecimal 44. 


Note: If you were to only import the clear key value of the host master key into CCA, you would not be 
able to migrate any keys. You need to factor in which master key variant encrypts the key in order to 
migrate it. 


The 8 byte values for creating master key variants are analogous to control vectors. The process of 
migrating keys can be thought of as changing control vectors on a key. The IBM 4758 CCA\IBM 4758 PCI 


Cryptographic Coprocessor CCA Basic Services Reference and Guide|“ describes a method for such a 


process. The method is the pre-exclusive-OR technique. If the clear key value of a key-encrypting key (the 
host master key in this case) is exclusive-ORed with control vector information before importing the key, 
you can effectively change the control vector for any key that this key-encrypting key imports. 


The pre-exclusive-OR technique works well if you are working with single-length keys. For double-length 


keys, the technique must be changed because the control vector for the right half of a CCA key is different 
than the control vector for the left half. To overcome this difference, import the key twice, as follows: 
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1. Create a 16 byte value such that each 8 byte half is identical to the left half of the control vector of the 
key you want to import. Use this 16 byte value in the pre-exclusive-OR technique to create an importer 
key-encrypting key that you can refer to as the "left-importer.” Only the left half of keys that are 
imported using this key-encrypting key will be valid. 

2. Create another 16 byte value such that each 8 byte half is identical to the right half of the control 
vector of the key you want to import. Use this 16 byte value in the pre-exclusive-OR technique to 
create an importer key-encrypting key. Using this importer key-encrypting key, only the right half of the 
keys that are imported will be valid 

3. Import the cross-domain twice: 

a. First use the key-encrypting key created in step 1 and save the left half of the result. 
b. Then use the key-encrypting key created in step 2 and save the right half of the result. 


4. In the final step, concatenate the left half of the result from step A with the right half of the result from 
step B. Place the combined results in a new key token. 


You now have a CCA double-length key that behaves like the cross-domain key from the Cryptographic 
Support for iSeries product. 


“Using IMPORTER key-encrypting keys” on page 123}summarizes all of the importer key-encrypting keys 


that are needed to import all of the cross-domain keys. It also describes how to create the importer 
key-encrypting keys. 


Method 2 


Note: You should only use this method if you feel comfortable with the security of your system and 
environment. This method is easier than the recommended method, but it presents a greater 
security risk for your cross-domain key files, since the cross-domain keys will be in clear form in 
application storage. 
1. Import the host master key into CCA as a data key by using the Clear_Key_Import (CSNBCKI) CCA 
API. Remember to perform an exclusive OR operation on the key with the values needed to produce 
data keys equivalent to the master key variants as follows: 
¢ Master key variant 1 encrypts sending cross-domain keys. Variant 1 is the result of an exclusive-OR 
operation of the host master key with 8 bytes of hexadecimal 88. 

¢ Master key variant 2 encrypts receiving cross-domain keys. Variant 2 is the result of an 
exclusive-OR operation of the host master key and 8 bytes of hexadecimal 22. 

¢ Master key variant 3 encrypts PIN cross-domain keys. Variant 3 is the result of an exclusive-OR 
operation of the host master key and 8 bytes of hexadecimal 44. 


You will have 3 different data keys after this step. 


2. Use the Decrypt (CSNBDEC) CCA API to decrypt the cross-domain keys to return the clear key 
values. Use the correct data key to decrypt it. 


3. Use the Key_Part_Import (CSNBKPI) CCA API to import the clear key into CCA. 


You should not consider this method to be secure. All of the keys will have been in clear form in 
application storage at some time during this method. 


Congratulations! You are now qualified to write a program to migrate cross-domain keys or you can 
change the following program example. 


Example: Migrating cross-domain keys into your 4758 Coprocessor, to migrate cryptographic 


support cross-domain keys: Change this program example to suit your needs for migrating 
Cryptographic Support for iSeries cross-domain key files into your 4758 Coprocessor. 
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[RRR K KKK KEIR KKK KKK KKK IKKE KKK IK KA KKK KKK KKK AKER AK KEK AKER KK | 
/* This program migrates keys stored in the file QACRKTBL in library */ 
QUSRSYS to key storage for Option 35 - CCA Cryptographic Service 
Provider. The QACRKTBL file contains cross domain keys that are 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


used for the Cryptographic Support licensed program, 5769-CR1. 
COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 */ 
This material contains programming source code for your 


consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 


of 


these program. All programs contained herein are 


provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


keys are migrated by the following steps: 


The master key used for 5769-CR1 passed as a parameter. 
Build importer keys using the master key, 8 bytes of a mask 
to create a variant, and a control vector. 

The file QACRKTBL is opened for input. 

A record is read. 

Import the key using the pre-exclusive OR process. CCA uses 


*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


control vectors while non-CCA implementations don't. 5769-CR1x/ 


creates master key variants similar to what 4700 finance 
controllers do. Since the control vector and master key 
variant material affect how the key is enciphered, the pre- 
exclusive OR process "fixes" the importer key so that it can 
correctly import a key. 

*SND keys are imported twice as an EXPORTER and OPINENC keys. 
*PIN keys are imported twice as a PINGEN and IPINENC keys. 
*RCV keys are imported as a IMPORTER key. 


6- A key record is created with a similar name as in QACRKTBL. 


For key names longer than 8 characters, a '.' will be 
inserted between the 8th and 9th characters. Also a 1 byte 


extension is appended that describes the key type. 
For example, MYKEY *RCV ---->  MYKEY.R 
MYKEKO0Q01 *RCV ----> MYKEKQ00.01.R 
For «SND and *PIN keys, a second key record is also created. 
For example, MYKEY *SND ---->  MYKEY.S 
MYKEY.0 
MYPINKEY *PIN ----> MYPINKEY.P 
MYPINKEY.1 


The key is written out to key store. 


Steps 4 through 7 are repeated until all keys have been 
migrated. 


Note: Input format is more fully described in Chapter 2 of 


IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: 
nonCCA master key - 8 bytes 


Example: 
CALL PGM(MIGRATECR) PARM(X'1C23456789ABCDEF ') 
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*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
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/* */ 


/* Note: This program assumes the device to be used is */ 
/* already identified either by defaulting to the CRPO1 x*/ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. x/ 
/* x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) */ 
/* CRTCMOD MODULE(MIGRATECR) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(MIGRATECR) MODULE (MIGRATECR) x*/ 
/* BNDSRVPGM(QCCA/CSNBKIM QCCA/CSNBKPI QCCA/CSNBKRC x/ 
/* QCCA/CSNBDEC QCCA/CSNBKRW) */ 
/* */ 
/* Note: Authority to the CSNBKIM, CSNBKPI, CSNBKRC, and CSNBKRW */ 
/* service programs in library QCCA is assumed. x/ 
/* */ 
/* */ 
/* The Common Cryptographic Architecture (CCA) verbs used are: x/ 
/* x/ 
/* Key Import (CSNBKIM) x/ 
/* Key Part_Import (CSNBKPI) */ 
/* Key Record Create (CSNBKRC) */ 
/* Key Record Write (CSNBKRW) */ 
/* x/ 
/* x*/ 


[KEK KKK RAK KEIRA KKK KKK KKK KK KK KKK KKK KKK KK KKK AKA KKK AREA KER KK | 


[BERR KKK KK EA AREA KK ERK K KKK KK IKKIEKAKEKK KEI A KEI KK EK KKK A KEKE | 


/* Retrieve various structures/utilities that are used in program. */ 
[BRK KERR KK EIA KAKA KKK KKK KK KEK K EI KKK KKK KKK IKKE IKKE A KKK K KER KK | 


#include <stdio.h> /* Standard I/0 header. */ 
#include <stdlib.h> /* General utilities. */ 
#include <stddef.h> /* Standard definitions. */ 
#include <string.h> /* String handling utilities. x/ 
#include "miptrnam.h" /* MI templates for pointer x/ 

/* resolution instructions. */ 
#include "csucincl.h" /* Header file for security API */ 


[KEK RK KKK KEIR ERA K KEK KKK KKK KKK KKK KKK AKI KKK KAKA KKK KEE KK KER KK | 


/* Declare function prototype to build tokens to import keys x/ 
[ REKRKE RAK KEIR KEI KK ERK K KIRKE AK KEK KEIRA AKI AKAIKE IKKE KEKE AKER | 


int buildImporter(char * token, 


char * clearkey, 
char * preXORcv, 
char * variant); 


[BRK KKK KKK EI KKK AK KERR KKK KKK KKK KKK KEI KKK KKK KK KKK AKER AK KEK AREA KER KK | 


/* Declare function prototype to import a non-CCA key and put it */ 
/* into key store. */ 
[BRK R KEK K KEIR KEI K KER KK KKK KKK KKK KK AK KAA KEK IKEA IKEA KEKE A KEKE | 


int importNonCCA(char * label, 


char * left_importer, 
char * right_importer, 
char * cv, 

char * encrypted_key); 


[ REKRK KKK KK EIR KAA K KKK KKK KKK KK IK KKK KKK KK KKK KK AK KEK AREA KEKE KE | 


/* Declares for working with files x/ 
[BRK R KKK KK EAR KEI KKK EKER KKK KEIR K AKA KEK KEI KK EKA A KEKE | 
#include <xxfdbk.h> /* Feedback area structures. x/ 
#include <recio.h> /* Record I/0 routines x/ 
_RFILE *dbfptr; /* Pointer to database file. x/ 
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_RIOFB_T 
~XXOPFB_T 


xdb_fdbk; 
*«db_opfb; 


/* 1/0 Feedback - data base file */ 


[BRK RK ERA KK EAR KER KKK EKER KERIKERI KK AKKEKKKEA KIKI KEE AKER KARE | 


/* Define the record for cross domain key file QACRKTBL */ 


[BRK K KKK KEIR KEK KKK KK KKK KKK KKK AK KA KK IKK KKK KKK KKK KKK A KKK K KEKE | 


struct 
{ 
char  label[10]; 
char  key_type; 
char __ key_value[8]; 
} key_rec; 


[BRK K RRR KK RAK KKK KKK KKK KKK KKK KKK IK KKK KKK KKK KKK EA KKK AREA AKER KK | 


/* Define the structure for key tokens */ 
[BRK K REAR KEIR KEK KKK KK EKER A KKK KK IKKE IKKE IKKE IKKE AKER AKER A AREA | 


typedef struct 


{ 


char __ tokenType; 

char reserved]; 

char MasterKeyVerifPattern[2]; 
char version; 

char reserved2; 

char flagBytel; 

char flagByte2; 

char __reserved3[8]; 

char leftHalfKkey[8]; 

char rightHalfKey[8]; 

char _controlVectorBase[8] ; 
char _rightControlVector[8]; 
char reserved4[12]; 

char tvv[4]; 


} key_token_T; 


[BRK RK ERK KKRA KK IKEA KK AKK EA AKER KERIKERI KEI KKK AK KEKE KERRIER | 
/* Declare control vectors used for building keys */ 
[BRK RK ERK KKRAKKEAK EEA K KEK KK EK KK ERK KER AK KK AK KAKA AKER EKER KER | 
char pingen_cv[16] = { 0x00, 0x22, Ox7E, 0x00, 

0x03, 0x41, 0x00, Ox00, 

0x00, 0x22, Ox7E, Ox00, 

0x03, 0x21, 0x00, 0x00}; 


char { 0x00, 
0x03, 
0x00, 


0x03, 


ipinenc_cv[16] 


iT} 
“~_ 


opinenc_cv[16] 0x00, 
0x03, 
0x00, 


0x03, 


char 


{ 0x00, 
0x03, 
0x00, 
0x03, 


char importer_cv[16] 


iT 
a 


0x00, 
0x03, 
0x00, 
0x03, 


char exporter_cv[16] 


0x21, 
0x41, 
0x21, 
0x21, 


0x24, 
0x41, 
0x24, 
0x21, 


0x42, 
0x41, 
0x42, 
0x21, 


0x41, 
0x41, 
0x41, 
0x21, 


Ox5F, 
0x00, 
Ox5F, 
0x00, 


0x77, 
0x00, 
0x77, 
0x00, 


0x7D, 
0x00, 
0x7D, 
0x00, 


0x7D, 
0x00, 
0x7D, 
0x00, 


0x00, 
0x00, 
0x00, 
0x00}; 


0x00, 
0x00, 
0x00, 
Qx00}; 


0x00, 
0x00, 
0x00, 
0x00}; 


0x00, 
0x00, 
0x00, 
0x00}; 


char importer_cv_part[16] = { 0x00, 0x42, Ox7D, 0x00, 
0x03, 0x48, 0x00, 0x00, 
0x00, 0x42, Ox7D, Ox00, 


Qx03, 0x28, 0x00, 0x00}; 
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char exporter_cv_part[16] = { 0x00, 0x41, 0x7D, 0x00, 
0x03, 0x48, 0x00, 0x00, 
0x00, 0x41, Ox7D, Ox00, 
0x03, 0x28, 0x00, 0x00}; 


[RRR RK KKK KK EAA RRA K KER KKK KKK KK KKK KK IK KKK AKAIKE RA KKK KKK AKER KK | 


/* Start of mainline code. 


*/ 


[BRK R KERIKERI KKK K KER KKK KKK AK KEK KKK KKK IKE KKK KIKI KKK KEK A KEKE | 


int main(int argc, char *argv[]) 


{ 


long i,gjok; /* Indexes for loops 
char key_label [64]; /* label of new key 
char key_label1[64]; /* label of new key 


[RHR KERR KEKE KK KEK KKK IKK A KKK KKK KKK AK KAKA KKK AKER AK ERK KEE | 


/* Declare importer keys - two keys are needed for each type */ 
[BRK RRR KKK IKK ER KKK KKK KEIR KERIKERI KEI KKK KEK AKER KER | 


char EXPORTER_importerL[64] ; 
char EXPORTER_importerR[64] ; 
char OPINENC_importerL[64] ; 
char OPINENC_importerR[64] ; 
char IMPORTER_importerL[64] ; 
char IMPORTER_importerR[64] ; 
char PINGEN_importerL[64] ; 

char PINGEN_importerR[64] ; 

char IPINENC_importerL[64] ; 
char IPINENC_importerR[64] ; 


[RHR KKK KKK EAA K RAKE KKK KKK K KKK KEK KAKA KKK KAKA KKK EKER | 


/* Declare variables to hold bit strings to generate master key */ 
/* variants. */ 
[RRR KKK KK EAA KKK K KKK KERR KKK KKK KK AK KAKA KKK AIK A AKER EKER | 
char variant1[16]; 
char variant2[16]; 
char variant3[16]; 


*/ 
*/ 
*/ 


[BRK RK ERK KEI KKK AK KKK KKK KKK KKK ERK K IK KKK KKK KKK AIK A KKK AKER A KER KK | 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Build the key tokens for each of the importer keys using 


Key_Token Build. Each key is built by using a variant, a control 
vector, and the clear key. Master key variant 1 is the result of 


an exlusive OR of the master key with hex '8888888888888888' , 
Master key variant 2 is the result of an exclusive OR of the 
master key with hex '2222222222222222', and Master key varient 3 
is the result of an exclusive OR of the master key with hex 
"A44gaggggggggaga', During the import operation, the control 
vector is exclusive OR'ed with the importer key. The effect of 


the control vector is overcome by including the control vector as 


key part. Then when the import operation is done, the exclusive 
OR operation will result in the original key. For double keys, 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


the left and right half of the control vector is not the same and */ 
therefore, XORing with the control vector will not result in the */ 
original key - only one half of it will be valid. So two keys are*/ 


needed - one for each half. 


*/ 


[RE KR KER AKKEAK KEIRA K EK KKK KKK AK KEKE KARE KKK EKA KEE AK KEK AREA KER | 


memset(variantl, 0x88, 16); 
memset(variant2, 0x22, 16); 
memset (variant3, 0x44, 16); 


if (buildImporter(EXPORTER_importerL, argv[1], 
exporter_cv, variantl) || 


buildImporter(EXPORTER_importerR, argv[1], 
&exporter_cv[8], variantl) || 


buildImporter(IMPORTER_importerL, argv[1], 
importer_cv, variant2) | 
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buildImporter(IMPORTER_importerR, argv[1], 
&importer_cv[8], variant2) || 


buildImporter(PINGEN importerL, argv[1], 
pingen_cv, variant3) || 


buildImporter(PINGEN importerR, argv[1], 
&pingen_cv[8], variant3) || 


buildImporter(IPINENC_importerL, argv[1], 
ipinenc_cv, variant3) || 


buildImporter(IPINENC_importerR, argv[1], 
&ipinenc_cv[8], variant3) || 


buildImporter(OPINENC_importerL, argv[1], 
opinenc_cv, variant1) || 


buildImporter(OPINENC_importerR, argv[1], 
&opinenc_cv[8], variant1)) 


printf("An error occured creating the importer keys\n"); 
returns; 
[BRK K RRR KK RAK KEK KKK KK KKK KKK KK KEK KK AK KIA KKK IKKE IKKE AKER A KKK K KEKE | 
/* Open database file. */ 


[RRR KKK KKK RAK KAA KKK KKK KKK KK KEK KK IK KIA KKK KKK KKK EA KKK KEK K KEKE | 


/* Open the input file. */ 
/* If the file pointer, */ 
/* dbfptr is not NULL, */ 
/* then the file was */ 
/* successfully opened. */ 


if (( dbfptr = _Ropen("QUSRSYS/QACRKTBL", "rr riofb=n")) 
\ 


NULL) 
{ 
db_opfb = Ropnfbk( dbfptr ); /* Get pointer to the */ 
/* File open feedback */ 
/* area. */ 
j = db_opfb->num_records; /* Save number of records*/ 


[BRK RK KER KK EAR KEIR KER AKER KEK KEKE IKKE KK KEIRA KEK AK KEA KEE KEKE | 

/* Read keys and migrate to key storage. */ 

[KEK KKK KEKE RK KKK KKK KK KIRKE KKK AK KKK KAKA AKER AKER KKK | 

for (i=1; i<=j; i++) /* Repeat for each record */ 

{ /* Read a record x/ 
db_fdbk = _Rreadn(dbfptr, &key_rec, 
sizeof(key_rec), __DFT); 


[RRR KKK KKK RIKKI KKK KKK KKK KKK KKK KK AK KKK KE KAKA KKK KAKA KEE KKK | 
/* Generate a key label for the imported keys. */ 
/* The key label will be similar to the label that was used for */ 
/* the QACRKTBL file. If the label is longer than 8 characters, */ 
/* then a period '.' will be inserted at position 8 to make it~ */ 
/* conform to label naming conventions for CCA. Also one x/ 
/* one character will be added to the end to indicate what type ~*/ 
/* of key. 5769-CR1 does not require unique key names across all*/ 
/* key types. CCA requires unique labels for all keys. x/ 
[BRK RK RRA KEKE IKKE AK KER AKER KEK KKK KK AKKEA KKK AKIRA A IKEA KEE ERE | 
memset ((char *)key_label,' ',64);  /* Initialize key label ~*/ 

/* to all blanks. */ 
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/* Copy first bytes of label */ 
memcpy((char *)key_label, (char *)key_rec.label,8); 


/* If label is longer than 8 characters, add a second element*/ 
if (key_rec.label[8] != ' ') 

{ 

key_label [8] veh 

key_label [9] key_rec. label [8]; 

key_label[10] = key_rec.label[9]; 

} 


/*x *SND keys and *PIN keys need to be imported twice so x/ 
/* make a second label */ 
if (key_rec.key_type != 'R') 

memcpy((char *)key_labell, (char *)key_label,64); 


/* Add keytype to label name. Search until a space is found */ 
/* and if less than 8, add the 1 character keytype. If it */ 
/x is greater than 8, add a second element with the keytype ~*/ 


/* 'R' is *RCV key, 'S' is *SND key, 'P' is *PIN key, */ 
/* 'I' is an IPINENC key and '0' is OPINENC key */ 
for (k=1; k<=11; k++) 
{ 
if (key_label[k] == ' ') 
if (k != 8) 


{ 
key_label[k] = key_rec.key_type; 


/* If this is a *SND or *PIN key, update the keytype ~*/ 
/* in the second label as well */ 
if (key_rec.key_type != 'R') 


memcpy((char *)key_labell, (char *)key_label,64); 
if (key_rec.key type == 'S') 

key_labell[k] = '0'; 
else 

key_labell[k] = 'I'; 


else 


{ 
key_label [8] ed 
key_label [9] key_rec.key_type; 


/* If this is a *SND or *PIN key, update the keytype ~*/ 
/* in the second label as well */ 
if (key_rec.key type != 'R') 


memcpy((char *)key_labell, (char *)key_label,64); 
if (key_rec.key_type == 'S') 

key_label1[9] = '0'; 
else 

key_label1[9] = 'I'; 


[RRR RK KERR EAR KEK AKER A KEK KKK IKK AK KEI KKK KKK AKI KKK KAKA AKER ERE | 


/* Check for the type of key that was in the QACRKTBL file x/ 
/* - S for SENDER key will become two keys - EXPORTER and OPINENC*/ 
/* - R for RECEIVER key will become IMPORTER key */ 
/* - P for PIN will become two keys - PINGEN and IPINENC */ 


116 iSeries: Cryptographic hardware 


/* Set the key id to the key token that contains the key under */ 
/* which the key in QACRKTBL is enciphered. */ 
/* Set the key_type SAPI parameter for the Secure_Key_Import verb*/ 
[BERR KKK KEKE IKKE AK KERIKERI KKK KKK KEK KK AKKEIK KE KA KE EK KERR K KE | 
if (key_rec.key_type == 'S') 
{ 
/* Import the exporter key x/ 
if (importNonCCA(key_label, 
EXPORTER_importerL, 
EXPORTER_importerR, 
exporter_cv, 
key_rec.key_value) ) 


printf("An error occured importing an exporter key\n"); 
break; 


} 


/* Import the OPINENC key x/ 
if (importNonCCA(key_labell, 
OPINENC_importerL, 
OPINENC_importerR, 
opinenc_cv, 
key_rec.key_value)) 
{ 
printf("An error occured importing an opinenc key\n"); 
break; 
} 
} 
else 
if (key_rec.key_type == 'R') 
{ 
/* Import the importer key */ 
if (importNonCCA(key_label, 
IMPORTER_importerL, 
IMPORTER_importerR, 
importer_cv, 
key_rec.key_value) ) 


{ 
printf("An error occured importing an importer key\n"); 
break; 
} 

} 

else 
{ 
/* Import the PINGEN key */ 


if (importNonCCA(key_label, 
PINGEN_importerL, 
PINGEN_importerR, 
pingen_cv, 
key_rec.key_value) ) 


{ 
printf("An error occured importing a PINGEN key\n"); 
break; 
} 
/* Import the IPINENC key */ 


if (importNonCCA(key_labell, 
IPINENC_importerL, 
IPINENC_importerR, 
ipinenc_cv, 
key_rec.key_value)) 


printf("An error occured importing an ipinenc key\n"); 
break; 
} 

} 
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} /* End loop 


repeating for each record «/ 


[BRK R KEK K KEIRA KKK KKK KKK KKK EA KK IK KIKI KEK KKK AIK E AK KEK KEE KARE KE | 


/* C 


lose database file. 


*/ 


[RRR RK KKK KEIR KAA KEKE KKK KKK IKK IK KKK KKK KKK KAKA KKK KKK K KER KK | 


} 


el 


if (dbfptr != NULL) 
_Rclose(dbfptr) ; 


se 


{ 


printf("An error occured openning th 


/* Close the file. */ 


/* End if file open leg */ 


e QACRKTBL file.\n"); 


/* End of main() */ 


[KEK KKK RAK K EIR A AKER KK KKK KKK KKK KK IK KKK KKK KKK KAKA KKK AREA KER EK | 


/* 
/* 
/* 
/* 
/* 


buildImporter creates an importer toke 
OR'ed with a variant and a control vec 
is XOR'ed in order to import non-CCA k 
in order to import from implementation 
master key variants to protect keys as 


n from a clearkey exclusive*/ 
tor. The control vector */ 
eys. The variant is XOR'ed*/ 
s that use different */ 
does 5769-CR1. x/ 


[KEK RK KAR KEI K KKK KKK KK KKK KKK KEKE KK KKK AKA KKK IKK AK KEK KKK AKER KK | 


int 


{ 


[ «ee 
/* D 
[*** 
char 
long 
long 
long 
long 
char 
char 
char 
char 
key_ 


buildImporter(char * token, 
char * clearkey, 
char * preXORcv, 
char * variant) 


KR KKK A KKK K EKA K KKK K KEK AKER AKER AKER EK | 


eclare variables used by the SAPI's «/ 

KR KIRA KKK AK KKK KKK KKK KKK ERK KER AKER KKK | 
rule_array[16] ; 
rule_array_count; 
return_code; 
reason_code; 
exit_data_length; 
exit_data[4]; 
keyvalue[16] ; 
keytype[8] ; 
ctl_vector[16]; 

token_T xtoken_ptr; 


[BRK RRR AK KEIR RRA K RRA K KAR KERR EK AKER AKER AKER KKK | 


/* B 


uild an IMPORTER token 


*/ 


[ REKRK KIRK KEIR ERIK KEIRA KKK IKKE KK KKK AKER AKER KKK | 
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memset(token, 0, 64); /* 
token_ptr = (key_token_T *) token; 
token_ptr->tokenType = 0x01; /* 
token_ptr->version = 0x03; /* 
token_ptr->flagBytel = 0x40; /* 
/* 
/* 
/* 
/* 
memcpy (token_ptr->controlVectorBase, i 
/* 
/* 
/* 
/* 


/* 
/* 
memcpy (token_ptr->tvv, "\xOA\xF5\x3A\x0 
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Initialize token to all Q's */ 


01 is internal token */ 
Version 3 token x/ 
High order bit is 0 so key */ 
is not present. The 40 */ 
bit means that CV is present*/ 


Copy control vector into */ 
the token. */ 
mporter_cv_part, 16); 

Copy TVV into token. This */ 
was calculated manually by */ 
setting all the fields and ~*/ 
then adding each 4 bytes of */ 
the token (excluding the */ 
TVV) together. */ 
0", 4); 


[KERR KKK KKK KK AK KAKA K KEK KKK IK KKK KKK KKK AKI KKK AAR AK KEKE | 
/* Import the control vector as a key part using Key_Part_Import */ 
[KERR K RAKE A KKK KERIKERI KK EAR AK KEK KKK AKER A KKK AKER EKER KER | 
exit_data_length = 0; 
rule_array_count = 1; 
memcpy(ctl_vector, preXORcv, 8); 
memcpy(&ctl_vector[8], preXORcv, 8); /* Need to copy the 
control vector into the 
second 8 bytes as well*/ 
memcpy(rule_array, "FIRST ", 8); 
CSNBKPI( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(char *) ctl_vector, 
(char *) token); 


if (return_code > 4) 


printf("Key_Part_Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 
return 1; 


} 


[RHR RK RRR KKK K RRA K KKK K KAKA KK KKK KKK KEK KKK IKEA KK AKER A KKK KE | 
/* Import the variant as a key part using Key Part_Import */ 
[BRK K ERK KER AK KRA KEIRA KKK KK EIR K KKK AKER IKEA IKEA AREA AKER KE | 
memcpy(rule_array, "MIDDLE ", 8); 
CSNBKPI( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(char *) variant, 
(char *) token); 


if (return_code > 4) 
{ 
printf("Key_Part_Import failed with return/reason codes \ 
sd/%d \n",return_code, reason_code) ; 
return 1; 


} 


[KERR KKK KKK AK KR A KKK KKK AK KKK KEIR KKK KEK KKK AKI KKK KAKA AKER KE | 
/* Import the clear key as a key part using Key Part_Import */ 
[BRK K ERA KKR IKKE IKEA KKK AK KK KK EAR KEK KKK AKER IKK K IKEA AREA AKER RE | 
memcpy(keyvalue, clearkey, 8); 
memcpy (&keyvalue[8], clearkey, 8); /* Make key double length«/ 
memcpy(rule_array, "LAST ", 8)3 
CSNBKPI( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(char *) keyvalue, 
(char *) token); 


if (return_code > 4) 
{ 
printf("Key_Part_Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 
return 1; 


} 


return 0; 


} 


[RRR RK RRR KK AK KEK KKK AK KKK KKK KKK IK KKK KKKK KK A KKK KKK KAKA AKER K KEKE AK | 
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/* importNonCCA imports a double length key into CCA from the x/ 
/* non-CCA implementation x/ 
[BRK RK ERIK KEIR K ERK KEK KKK KEIR KEKE KK EAR KAKA KER AAR ERK | 


int importNonCCA(char * label, 


char * left_importer, 

char * right_importer, 
char * cv, 

char * encrypted_key) 


{ 


[KEK RRR KKK EA KKRA KK AK KK AK KERR KER KK ERK KER EK | 


/* Declare vaiables used by the SAPIs x*/ 
[RE KR KEK K EEA KKR IKKE IKEA KEKE KER KK ERE KERR | 
long return_code, reason_code; 
char exit_data[4]; 

long exit_data_length; 

long rule_array_count; 

char rule_array[24]; 

char keytoken[64]; 

char external key[64]; 

char keyvalue[16] ; 

char keytype[8] ; 

char «importer; 

char mkvp[2]; 

key_token_T *token_ptr; 

int tvv, tvv_part; 

char *tVV_pOS3 


[ BRK KKK KKK ERK EKA K KKK K KKK KKK KKK KK ERK KER AKER | 


/* Build an external key token to IMPORT from */ 


[KEK RK KKK KK ERK KKK KKK KKK KKK AK KEK KK ERK KKE RE | 


memset ((void *)externalkey,'\00',64); 
token_ptr = (key_token_T *)externalkey; 


token_ptr->tokenType = 0x02; /* 02 is external token 
token_ptr->version = 0x00; /* Version @ token 
token_ptr->flagBytel = OxC0; /* High order bit is 1 so 


/* key is present. The 
/* 40 bit means that CV 
/* is present 


memcpy (token_ptr->controlVectorBase, cv, 16); /* Copy control 
vector into token 


memcpy (token_ptr->leftHalfkey,encrypted_key, 8); 


memcpy (token_ptr->rightHalfKey,encrypted_key, 8); 


[BRK K RRA K ERA KKK KKK KKK AKER KER AK KKK KK ERK | 
/* Calculate the TVV by adding every 4 bytes */ 
[EK RK ERIK ERIK REAR REAR K EK KKK AKER AK KEKE EAKRE RK | 
tvv_pos = externalkey; 
tvv = 0; 
while (tvv_pos < (externalkey + 60)) 
{ 
memcpy ((void*)&tvv_part,tvv_pos,4); 
tvv += tvv_part; 
tvv_pos += 4; 
} 
memcpy(token_ptr->tvv, (void*)&tvv, 4); 


/* Copy key 
into left half 
/* Copy key 
into right half 


[BRK RK RRR KK ERK KR AK KKK KK KKK KKK KKK KK AK KAKA KKK KEKE RAK ERK | 


/* Import the left half of the key using Key_Import and */ 
/* the importer built with left half of the control vector */ 


[BERR KEK K KEIRA KKK KEIR KEK KKK KKEKKK EK KKEAKK EKA K ER EKERKK | 
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exit_data_length = 0; 
memcpy(keytype, "TOKEN ", 8); 
memset ((void *)keytoken, '\00',64); 
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CSNBKIM( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(char *) keytype, 
(char *) externalkey, 
(char *) left_importer, 
(char *) keytoken); 


if (return_code > 4) 
{ 
printf("Key_ Import failed with return/reason codes \ 
sd/%d \n",return_code, reason_code); 
return 1; 


} 


[KEK RK ERR KKK AKER A KKK KKK A KKK KKK ERK ERE KERR | 
/* Save left half of key out of key token */ 


[KEK RK ERK KERIKERI KERIKERI KEK EKER KEKE EKER ER | 


memcpy(keyvalue, &keytoken[16], 8); 


[BERR KEK K RRA K REAR A KKK KK EKER KER IKK IKKE KAKA AKER AKER | 
/* Import the right half of the key using Key_Import and */ 
/* the importer built with right half of the control vector*/ 
[BRK K RRR KK AK RRA KKK AK KKK KKK KKK KKK KER AK KK AK KK AK KEK KIER AER ERK | 
memcpy(keytype, "TOKEN ", 8); 
memset ((void *)keytoken, '\00',64); 
CSNBKIM( &return_code, &reason_code, &exit_data_length, 
(char *) exit_data, 
(char *«) keytype, 
(char *) externalkey, 
(char *) right_importer, 
(char *) keytoken); 


if (return_code > 4) 
{ 
printf("Key_ Import failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 
return 1; 


} 


[RRR RK KKK KR AK RRA K KKK K KKK KEK AKER KER ARK KK | 
/* Save right half of key out of key token */ 
[RRR R KERR KK AK RRA K KKK K KKK KEK AKER AKER KKK | 


memcpy (&keyvalue[8], &keytoken[24], 8); 


[RHR RK KKK KR AK KEK KKEA KKK KKK KKK IK KKK KKK AK KAKA KKK KEKE AKER KKK | 


/* Get master key verification pattern from the last key token built 


*/ 


[BRK RK RRA KKR IKKE IKKE A KKK K KEK KK EAR KER IKK IKEA KKK A KK EAA KEA AKER AKER A KEE | 


mkvp[0] 
mkvp[1] 


keytoken[2]; 
keytoken[3]; 


[BRK RK RAK KR KKK IKEA KERIKERI AK KEIR KEK KKK AKER AKER AK ERA KER | 


/* Build an internal key token using both key halves just */ 
/* imported and using the master key verification pattern */ 
[KERR KKK KERR AK KR AK KKK K KKK KAKI KK AK KEKE AKER AKER | 

memset((void *)keytoken, '\00',64); 

exit_data_length = 0; 

token_ptr = (key_token_T *)keytoken; 


token_ptr->tokenType = 0x01; /* 01 is internal token 
token_ptr->version = 0x03; /* Version 3 token 
token_ptr->flagBytel = 0xCQ; /* High order bit is 1 so 


/* key is present. 


/* 40 bit means that CV is 


/* present 
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/* Set the first byte of  ¥*/ 

/* Master key verification */ 

/* pattern. */ 
mkvp[0] ; 

/* Set the second byte of +*/ 

/* Master key verification */ 

/* pattern. */ 
mkvp[1]; 


token_ptr->MasterKeyVeri fPattern[0] 


token_ptr->MasterKeyVeri fPattern[1] 


/* Copy control vector intox/ 
/* token */ 
memcpy (token_ptr->controlVectorBase, cv, 16); 
memcpy (token_ptr->leftHalfKey, keyvalue, 16); /*Copy key to token */ 


[KERR KKK AK ERIK KERR KKK KKK KKK KKK ERA KK AK REA KRERK | 
/* Calculate the TVV by adding every 4 bytes */ 
[BRK RKE RAKE RAK RRA K KEKE KEKE KEI KER AK KEKE | 
tvv_pos = externalkey; 

tvv = 0; 

while (tvv_pos < (externalkey + 60)) 


memcpy ((void*)&tvv_part,tvv_pos,4); 
tvv += tvv_part; 
tvv_pos += 4; 
} 
memcpy(token_ptr->tvv, (void*)&tvv, 4); 


[RRR KERR KK ERK K RAKE KK KKK KKK KK ERK KER AKER KK | 


/* Create a Key Record in Key Store */ 
[BRK KKK RA KK RAKE EAA KEK KEK KEKE KKK RK KEKE REE | 
exit_data_length = 0; 
CSNBKRC((long *) &return_code, 
(long *) &reason_code, 
(long *) &exit_data_length, 
(char *) exit_data, 
(char *) label); 


if (return_code > 4) 
{ 
printf("Key_Record Create failed with return/reason codes \ 
sd/%d \n",return_code, reason_code) ; 
return 1; 


} 


[KEK KK KKK KEI K KKK KKK KK KAKA KEK KK EKA KER KKK EK | 


/* Write the record out to Key Store x/ 
[BRK RK ERA KEKE IKKE RK KER AKER K KEKE A KKK EKER EKER EK | 
CSNBKRW((long *) &return_code, 

(long *) &reason_code, 

(long *) &exit_data_length, 

(char *) exit_data, 

(char *) keytoken, 

(char *) label); 


if (return_code > 4) 
printf("Key_Record_ Write failed with return/reason codes \ 
%d/%d \n",return_code, reason_code); 


return 1; 


} 


return 0; 
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Using IMPORTER key-encrypting keys: To import all types of cross-domain keys you will need the 
following IMPORTER key-encrypting keys: 


1. A KEK for importing the left half of exporter keys. 


Create this key using the clear host master key, the left half of an exporter key-encrypting key control 
vector, and 16 bytes of hex 88. 


2. A KEK for importing the right half of exporter keys 


Create this key using the clear host master key, the right half of an exporter key-encrypting key 
control vector, and 16 bytes of hex 88. 


3. A KEK for importing the left half of importer keys. 


Create this key using the clear host master key, the left half of an importer key-encrypting key control 
vector, and 16 bytes of hex 22. 


4. A KEK for importing the right half of importer keys. 


Create this key using the clear host master key, the right half of an importer key-encrypting key 
control vector, and 16 bytes of hex 22. 


5. A KEK for importing the left half of OPINENC keys. 


Create this key using the clear host master key, the left half of an OPINENC key control vector, and 
16 bytes of hex 88. 


6. A KEK for importing the right half of OPINENC keys. 


Create this key using the clear host master key, the right half of an OPINENC key control vector, and 
16 bytes of hex 88. 


7. A KEK for importing the left half of IPINENC keys. 


Create this key using the clear host master key, the left half of an IPINENC key control vector, and 16 
bytes of hex 44. 


8. A KEK for importing the right half of IPINENC keys. 


Create this key using the clear host master key, the right half of an IPINENC key control vector, and 
16 bytes of hex 44. 


9. A KEK for importing the left half of PINGEN keys. 


Create this key using the clear host master key, the left half of a PINGEN key control vector, and 16 
bytes of hex 44. 


10. A KEK for importing the right half of PINGEN keys. 


Create this key using the clear host master key, the left half of a PINGEN key control vector, and 16 
bytes of hex 44. 


11. A KEK for importing the left half of PINVER keys. 


Create this key using the clear host master key, the left half of a PINVER key control vector, and 16 
bytes of hex 44. 


12. A KEK for importing the right half of PINVER keys. 
Create this key using the clear host master key, the left half of a PINVER key control vector, and 16 


bytes of hex 44. 
Migrate key store files 


Procedure here..explain the process of migrating key store files from the Common Cryptographic 
Architecture Cryptographic Service Provider for iSeries Services. 


Manage the 4758 Cryptographic Coprocessor 

This section is mainly for OS/400 application use of the 4758 Coprocessor. If you are using multiple 
Coprocessors with SSL, see|“Manage multiple 4758 Cryptographic Coprocessors” on page 179 and|*Clone| 
master keys” on page 189) 
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After you set up your 4758 Coprocessor, you can begin writing programs to make use of your 4758 
Coprocessor’s cryptographic functions. You can use programs to perform these tasks: 


. [‘Log on or off of the 4758 Cryptographic Coprocessor’| to work with role-restricted APIs. 
if you plan to keep records of your DES and PKA keys. 
and storing them in a DES key store. 


“Encrypt or decrypt a file” on page 151 
“Work with PINs” on page 157 


“Generate and verify a digital signature” on page 170 


“Manage multiple 4758 Cryptographic Coprocessors” on page 17: 


“Clone master keys” on page 189 


Note: Many of the pages in this section include one or more program examples. Change these programs 
to suit your specific needs. Some require that you change only one or two parameters while others 
require more extensive changes. For security reasons, IBM recommends that you individualize 
these program examples rather than using the default values provided. 


9 
when using multiple 4758 Coprocessors. 


Log on or off of the 4758 Cryptographic Coprocessor 
Logging on 


You need to log on only if you wish to use an API that uses an access control point that is not enabled in 
the default role. Log on with a profile that uses a role that has the access control point you want to use 
enabled. 


After you log on to your 4758 Coprocessor, you can run programs to utilize the cryptographic functions for 
your 4758 Coprocessor. You can log on by writing an application that uses the Logon_Control (CSUALCT) 
API verb. Two example programs are provided for your consideration. One of them is written in ILE C, 
while the other is written in ILE RPG. Both perform the same function. 


¢ |“Example: ILE C program for logging on to your 4758 Coprocessor” 
* |“Example: ILE RPG program for logging on to your 4758 Coprocessor’ on page 127 


Logging off 


When you have finished with your 4758 Coprocessor, you should log off of your 4758 Coprocessor. You 
can log off by writing an application that uses the Logon_Control (CSUALCT) API verb. Two example 
programs are provided for your consideration. One of them is written in ILE C, while the other is written in 
ILE RPG. Both perform the same function. 


* |“Example: ILE C program for logging off of your 4758 Coprocessor” on page 129 
* |“Example: ILE RPG program for logging off of your 4758 Coprocessor’ on page 131 


Note: If you choose to use the program examples provided, change them to suit your specific needs. For 
security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Example: ILE C program for logging on to your 4758 Coprocessor 
Change this program example to suit your needs for logging on to your 4758 Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


eases caneeeae ses eessee se eee = Se aae ae ae aa es Hos Ses eee aes= ase aaa ae=esee */ 
/* Log on to the 4758 card using your profile and passphrase. x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1, 5722-SS1 (C) IBM CORP. 1999, 2000 x/ 
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#i 


#i 
#i 
#i 


#d 
#d 
#d 


in 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these program. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 

Note: This verb is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 

Parameters: 

none. 
Example: 
CALL PGM(LOGON) 
Note: This program assumes the card with the profile is 


already identified either by defaulting to the CRPO1 
device or by being explicitly named using the 
Cryptographic_Resource Allocate verb. Also this 
device must be varied on and you must be authorized 
to use this device description. 


Use these commands to compile this program on iSeries: 
ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(LOGON) SRCFILE(SAMPLE) 

CRTPGM PGM(LOGON) MODULE(LOGON) BNDSRVPGM(QCCA/CSUALCT) 


Note: Authority to the CSUALCT service program in the 
QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verb used is 


Logon_Control (CSUALCT). 
nclude "csucincl.h" /* header file for CCA Cryptographic 
/* Service Provider for iSeries 
nclude <stdio.h> 


nclude <string.h> 
nclude <stdlib.h> 


efine ERROR -1 
efine OK 0 
efine WARNING 4 


t main(int argc, char *argv[]) 


/* standard CCA parameters 


| Raseeeeseeseess ta =sea ease as soe eS eee eS see eee aes oe a eeeea 
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long return_code = 0 
long reason_code = 0; 
th 


long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 


char profile[8]; 

long auth_parm_length; 
char auth_parm[4]; 
long auth_data_length; 
char auth_data[256]; 


/* set rule array keywords 
memcpy(rule_array,"LOGON PPHRASE ", 16); 


/* Check for correct number of parameters 
if (argc < 3) 


{ 
printf("Usage: CALL LOGON ( profile ‘pass phrase')\n"); 
return(ERROR) ; 
} 
/* Set profile and pad out with blanks 
memset(profile, ' ', 8); 


if (strlen(argv[1]) > 8) 
{ 


printf("Profile is limited to 8 characters.\n"); 
return(ERROR) ; 


} 
memcpy(profile, argv[1], strlen(argv[1])); 


/* Authentication parm length must be 0 for logon 
auth_parm_length = 0; 


/* Authentication data length is length of the pass-phrase 
auth_data_length = strlen(argv[2]); 


/* invoke verb to log on to the 4758 card 


CSUALCT( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
profile, 
&auth_parm_length, 
auth_parm, 
&auth_data_length, 
argv[2]); 


if (return_code != OK) 


{ 


printf("Log on failed with return/reason codes %1d/%ld\n\n", 


return_code, reason_code) ; 


} 
else 
printf("Logon was successful\n"); 
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*/ 
*/ 


*/ 


Example: ILE RPG program for logging on to your 4758 Coprocessor 
Change this program example to suit your needs for logging on to your 4758 Coprocessor. 


Note: Read the/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKKK KK KKK KK KEK KKK ERK KKK KKK KER KK KEKE KK RRR KK RE KK RR ERER KERR RK 
D* LOGON 

Dx« 

D* Log on to the 4758 Cryptographic Coprocessor. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx 

Dx Parameters: Profile 

Dx Pass-phrase 

Dx« 

D* Example: 

D* CALL PGM(LOGON) PARM(PROFILE PASSPRHASE) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(LOGON) SRCFILE(SAMPLE) 
D* CRTPGM PGM(LOGON) MODULE (LOGON) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx 

D* Note: Authority to the CSUALCT service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 

Dx« 

D* This program assumes the card with the profile is 

Dx already identified either by defaulting to the CRPO1 

D* device or by being explicitly named using the 

D* Cryptographic_Resource Allocate verb. Also this 

D* device must be varied on and you must be authorized 

Dx to use this device description. 

DA KRKKKKKKK KKK KKK KER KKK ERK KKK KKK KKK KK RRR KK KR ERR KR ERK R RK RRERKER 


D)xeSSeeseesessesoSsaoesaSes sae sessesseSeesoesesaae 5 
D* Declare variables for CCA SAPI calls 

PkeSseeaesae cee sseseeee see ee sess eee see sees esses 
Dx *x Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx «x Exit data 
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DEXITDATA S 
Dx« 
DRULEARRAYCNT Ss 
Dx 


DRULEARRAY S 
Dx ** 
DUSERID S 
Dx« ** 
DAUTHPARMLEN S 
Dx« ** 
DAUTHPARM S 
Dx **k 
DAUTHDATALEN Ss 
Dx« ** 
DAUTHDATA S 
Dx 


4 
Rule array count 
9B 0 
Rule array 
16 
Userid parm 
8 
Authentication parameter length 
9B 0 INZ(0) 
Authentication parameter 
10 
Authentication data length 
9B 0 INZ(0) 
Authentication data 
50 


DA KRAK KKK KK KK ERK KKK KKK KERR KERR RRR KERR RR RRR KK REE KEKE RR KKK EERE 


D* Prototype for Logon Control (CSUALCT) 


DARK R KKK KKK KER KKK KKK KK ERK KKK ERK KEKE KEK KERR KKK KER KEK RRR KKK ERKE KEK 


DCSUALCT 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DRARRAYCT 
DRARRAY 
DUSR 
DATHPRMLEN 
DATHPRM 
DATHDTALEN 
DATHDTA 

Dx 


PR 


9B 0 
9B 0 
9B 0 
4 
9B 0 
16 
8 
9B 0 
10 
9B 0 
50 


DAR RKK KKK KKK KER KK KEK KKK ERK KKK ERK KK RRR RRR KKK KER KEK RRR KK RRR RRKERERE 


Dx Declares for sending messages to job log 
DA KRKKKKKKK KK ERK KKK KKK KERR KERR RRR KERR RRR RRR KKK ERR ER KERR RERRRRERERE 


PxeestecSete ec See eee eases se eee eee cee Se See eee eee See ee ee 
Dx ** Declares for sending messages to the 
Dx ** job log using the QMHSNDPM API 
ee eee ee eee ee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 
D DS 
DMSGTEXT 1 75 
DFAILRETC 41 44 
DFAILRSNC 46 49 
DMESSAGEID S 7 INZ(' ') 
DMESSAGEFTLE Ss 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 
DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ty 
DSTACKCOUNTER S 9B 0 INZ(2) 
DERRCODE DS 
DBYTESIN 1 4B 0 INZ(0) 
DBYTESOUT 5 8B 0 INZ(0) 
Dx 
CK KKK KKK KKK KK KKK KKK KEK KKK ERE RK EKER KEK RRR ERR EKER KERR ERE KERR ERR ERE 
Cx START OF PROGRAM * 
Cx« * 
CekssSesceceeseese acest esse ecee cee see Seee eee ee eeieeeecseicee ses * 
C *ENTRY PLIST 
C PARM USERID 
C PARM AUTHDATA 
Ckteee sees ecceaseeeseceeceeee Seco e ses e se SS sees ee se ssa coe sess * 
Cx Set the keywords in the rule array * 
Oksseck eee aca tees eowetsece ee sese sce see ee eee see eee ate sea Se * 
C MOVEL "LOGON =! RULEARRAY 
C MOVE "PPHRASE ! RULEARRAY 
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** 


(Xeee seen eseneseceeeeseee sees ecsseesensees 
Cx Get the length of the passphrase 
C¥eeeeteseseesne assesses scescessseesecnas 
C EVAL 

Cx« 


RULEARRAYCNT 


AUTHDATALEN = %LEN(%TRIM(AUTHDATA) ) 


CR KKK KK KEKE KK KK KKK KR EKER KER ERK KK EKER RRR EK REE REK ERK ERERKERKERR ERE 


Cx Call Logon Control SAPI 


CR KKK KKK KKK KKK KEK RE KEK KEK ERK KK RK ER KKK EK KERR ERE RK RR ERE RE RK ERR ERE 


C CALLP CSUALCT 
C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

CxkeeSeeeecece sees etee * 

Cx Check the return code * 
Ckxeeseesesesesesocssceco * 

C RETURNCODE IFGT 0 

Cx Keecsaasssses=ssesseoe5 * 
Cx * Send error message * 
Cx kobe eSavcccsceseeesseces * 
C MOVE MSG(1) 

C MOVE RETURNCODE 
C MOVE REASONCODE 
C EXSR SNDMSG 
Cx 

C ELSE 

Cx NeSessoussssSssossosssss * 
Cx * Send success message * 
Cx Keeeecicsvsose sees es eeee * 
C MOVE MSG (2) 

C EXSR SNDMSG 
Ce 

C ENDIF 

Cx 

C SETON 

Cx 


(RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
USERID: 
AUTHPARMLEN: 
AUTHPARM: 
AUTHDATALEN: 
AUTHDATA) 


MSGTEXT 
FAILRETC 
FAILRSNC 


MSGTEXT 


CR KKK KKK KKK KKK KKK RE KEK KEK ER KEK KKK ER KKK EKER KER ERE RR ER ERK RK ERR ERE 


Cx Subroutine to send a message 


CRRA KKK KKK KKK KKK KR EKER KER ER KERR RK ERK RRR EER EKER ERR EKER ERERREERE 


C SNDMSG BEGSR 

CALL "QMHSNDPM' 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
ENDSR 


* 


ODO: OOOO0 


MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 
ERRCODE 


CSUALCT failed with return/reason codes 9999/9999' 
The request completed successfully 


LR 


Example: ILE C program for logging off of your 4758 Coprocessor 
Change this program example to suit your needs for logging off of your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
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/* Log off the 4758 Cryptographic CoProcessor 

/* 

/* 

/* COPYRIGHT 5769-SS1, 5722-SS1 (C) IBM CORP. 1999, 2000 

/* 

/* This material contains programming source code for your 
/* consideration. These examples have not been thoroughly 
/* tested under all conditions. IBM, therefore, cannot 

/* guarantee or imply reliability, serviceability, or function 
/* of these program. All programs contained herein are 

/* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


/* these programs and files. 


/* 

/* 

/* Note: This verb is more fully described in Chapter 2 of 
/* IBM 4758 CCA Basic Services Reference and Guide 
/* (SC31-8609) publication. 

/* 

/* Parameters: 

/* none. 

/* 

/* Example: 

/* CALL PGM(LOGOFF) 

/* 

/* 

/* Note: This program assumes the card with the profile is 
/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource Allocate verb. Also this 
/* device must be varied on and you must be authorized 
/* to use this device description. 

/* 

/* 


/* Use these commands to compile this program on iSeries: 
/* ADDLIBLE LIB(QCCA) 

/* CRTCMOD MODULE(LOGOFF) SRCFILE(SAMPLE) 

/* CRTPGM PGM(LOGOFF) MODULE(LOGOFF) BNDSRVPGM(QCCA/CSUALCT) 
/* 

/* Note: Authority to the CSUALCT service program in the 

/* QCCA library is assumed. 

/* 

/* The Common Cryptographic Architecture (CCA) verb used is 
/* Logon_Control (CSUALCT). 

/* 


#include "csucincl.h" /* header file for CCA Cryptographic 
/* Service Provider for iSeries 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 


#define ERROR -1 
#define OK 0 


int main(int argc, char *argv[]) 


{ 
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/* standard CCA parameters */ 
| #seshesesoseestassesseesessacseoes eset eos ee nee aeeee ese «/ 
long return_code = 0; 
long reason_code = 0; 
long exit_data_length 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count 


I 
ine) 
we 


I 
rR 
we 


[RseessesesstesescosecdsesSssesscsosseesaseses sos seaeseeeesoeesessesss «/ 
/* fields unique to this sample program */ 
| #eeseSseseseaseassohaseseeesesetese see seo eso se ease sees secseesseeS «/ 
char profile[8]; 

long auth_parm_length; 

char * auth_parm = " "3; 

long auth_data_length = 256; 

char auth_data[300] ; 


/* set rule array keywords to log off */ 
memcpy(rule_array,"LOGOFF ",8); 


rule_array_count = 1; 


/* Both Authenication parm and data lengths must be 0 x/ 
auth_parm_length = 0; 
auth_data_length = 0; 
/* Invoke verb to log off the 4758 Cryptographic CoProcessor x/ 


CSUALCT( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
profile, 
&auth_parm_length, 
auth_parm, 
&auth_data_length, 
auth_data); 


if (return_code != OK) 


printf("Log off failed with return/reason codes %1d/%ld\n\n", 
return_code, reason code); 

return (ERROR) ; 

} 
else 

{ 

printf("Log off successful\n"); 

return (OK); 

} 

} 


Example: ILE RPG program for logging off of your 4758 Coprocessor 
Change this program example to suit your needs for logging off of your 4758 Coprocessor. 


Note: Read the/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA RRA K KARR KKK KKK KK ERK KK RRR KKK KKK KER KEK KKK KKK RRR KK RE KK RR ERER KERR RK 
Dx LOGOFF 

Dx« 

Dx Log off from the 4758 Cryptographic Coprocessor. 

* 

# 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 
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Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. 
D* these programs and files. 


Dx 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx 

D* Example: 

D* CALL PGM(LOGOFF) 

Dx« 


Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(LOGOFF) SRCFILE(SAMPLE) 
D* CRTPGM PGM(LOGOFF) MODULE(LOGOFF) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUALCT service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 

Dx« 

D* This program assumes the card with the profile is 

Dx already identified either by defaulting to the CRPO1 

D* device or by being explicitly named using the 

D* Cryptographic_Resource Allocate verb. Also this 

D* device must be varied on and you must be authorized 

Dx to use this device description. 

DARK AK KKK KKK KER KKK KEK KKK ERK KKK ERK KK RRR KER EK KK KER KERR KEKE RRR RRR KRERE 


IBM provides no program services for 


DkeeeecSecceeooteees tec escslocosesee lee cSssce sss cos 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXTTDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT 5 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Userid parm 

DUSERID S 8 

Dx ** Authentication parameter length 
DAUTHPARMLEN S 9B 0 INZ(0) 

Dx ** Authentication parameter 
DAUTHPARM S 8 

Dx ** Authentication data length 
DAUTHDATALEN Ss 9B 0 INZ(0) 

Dx ** Authentication data 
DAUTHDATA S 8 

Dx« 


DARK KK KKK KKK KER KKK KEK KKK ERK KKK ERK KEKE KEK KERR KEK KEKE RR KKK KERR RRR KEK 


Dx Prototype for Logon Control (CSUALCT) 
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DA KRKKKKKKK KKK KKK KER KKK ERK KKK KKK KKK KEK KEKE KKK KER KEK REK KKK EREK ER 


DCSUALCT PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DUSR 8 

DATHPRMLEN 9B 0 

DATHPRM 8 

DATHDTALEN 9B 0 

DATHDTA 8 

eee eee eee 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
ee eee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ) 
DMESSAGEFILE S 21 INZ(' ") 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CARR KK KKK KKK KK KKK KEKE KEK KEK ERK KK EKER KKK RK KERR ERE RK RR ERE RK REK ERR ERE 
Cx START OF PROGRAM * 
Cx* * 
(Xeseee ee reenensccseesiee sce sees sesensHesreeenceueesseeseeses * 
Cx Set the keywords in the rule array * 
ee ee ee ee * 
C MOVEL "LOGOFF! RULEARRAY 

¢ Z-ADD 1 RULEARRAYCNT 

Cx« 


CR KKK KKK KKK KK KKK KR EKER KEK ERK KK RK ER KKK EKER KEKE RK RR ER ERE RK ERR ERE 


Cx Call Logon Control SAPI 


CR KKK KK KKK KKK KKK KERR EKER KER ER KERR RK ERK RK EK EER EKER KERR EKER KERR ERR 


C CALLP CSUALCT (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C USERID: 

C AUTHPARMLEN: 
C AUTHPARM: 

C AUTHDATALEN: 
C AUTHDATA) 
Cxseocsocssessesecsecsecs * 

Cx Check the return code * 

Cksseseeececceceeceeececs * 

C RETURNCODE IFGT 0 

Cx* Wossssccsssssessosssscs * 

Cx * Send error message * 

Cx* a a * 

C MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 
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Cx 


C ELSE 

Cx Feseeeeseestssse see eee es * 

Cx * Send success message * 

Cx Kee ee Sseese sas seoesess * 

C MOVE MSG(2) MSGTEXT 
C EXSR SNDMSG 

Cx 

C ENDIF 

Cx 

C SETON LR 
Cx 


CR KKK KKK KKK KKK KER EKER KER ERE KK RK ERE RR EKER ER ERE RR ERE REE ERR 


Cx Subroutine to send a message 
CR K KK KKK KKK KK KKK KR KK EK KKK ERE KK EKER KERR EKER RRR ERK RR ERE REE ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx« 


** 


CSUALCT failed with return/reason codes 9999/9999' 
The request completed successfully 


Query status or request information 


You can query your 4758 Coprocessor to determine characteristics such as which algorithms are enabled, 
the key lengths it supports, the status of the master key, the status of cloning, and the clock setting. The 
easiest and fastest way to query the 4758 Coprocessor is to use the 4758 Cryptographic Coprocessor 
configuration web-based utility. Click on Display configuration and then select a device, then select items 
you want to display. 


If you would prefer to write your own application to query the Coprocessor, you can do so by using the 
Cryptographic_Facility_ Query (CSUACFQ) API verb. Two example programs are provided for your 


consideration. |“Example: Querying the status of your 4758 Coprocessor’| uses the STATEID and 
TIMEDATE keywords, while|“Example: Requesting information from your 4758 Coprocessor’ on page 137 


prompts the user for the second required keyword. 


The}IBM 4758 PCI Cryptographic Coprocessor CCA Basic Services Reference and Guide} describes 


the Cryptographic_Facility_Query (CSUACFQ) security application programming interface, the types of 
information that you can request, and the format of the information that is returned. 


Example: Querying the status of your 4758 Coprocessor 
Change this program example to suit your needs for querying the status of your 4758 Coprocessor. 


| ee ee ee eee «/ 
/* Query the 4758 card for status or other information. x/ 
/* This sample program uses the STATEID and TIMEDATE keywords. x/ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 x/ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
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/* of these program. All programs contained herein are 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


/* these programs and files. 


/* 

/* 

/* Note: This verb is more fully described in Chapter 2 of 
/* IBM 4758 CCA Basic Services Reference and Guide 

/* (SC31-8609) publication. 

/* 

/* Parameters: 

/* none. 

/* 

/* Example: 

/* CALL PGM(QUERY) 

/* 

/* 

/* Note: This program assumes the device to use is 

/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource Allocate verb. Also this 

/* device must be varied on and you must be authorized 
/* to use this device description. 

/* 


/* Use these commands to compile this program on iSeries: 
/* ADDLIBLE LIB(QCCA) 

/* CRTCMOD MODULE(QUERY) SRCFILE(SAMPLE) 

/* CRTPGM PGM(QUERY) MODULE(QUERY) BNDSRVPGM(QCCA/CSUACFQ) 


/* Note: Authority to the CSUACFQ service program in the 
/* QCCA library is assumed. 


/* The Common Cryptographic Architecture (CCA) verb used is 
/* Cryptographic_Facility_Query (CSUACFQ). 


#include "csucincl.h" /* header file for CCA Cryptographic 


/* Service Provider for iSeries 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 


[ ReereSeeeeeeeotesee Ses eee sete ses ae ees see eee eee eee tees ace see SeS 
/* standard return codes 
Reece wees soenes esse ceeeees=aees=s= See ees eae a a= sae eee === 
#define ERROR -1 
#define OK 0 
#define WARNING 4 


#define IDSIZE 16 /* number of bytes in environment ID 


#define TIMEDATESIZE 24 /* number of bytes in time and date 


int main(int argc, char *argv[]) 


{ 


| ee ee eee 


long return_code = 0; 
long reason_code = 0; 
long exit_data_length = 2; 
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char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 
char rule_array2[3] [8]; 


long verb_data_length = 0; /* currently not used by this verb 
char * verb data = " "3; 


/* set keywords in the rule array 
memcpy (rule_array,"ADAPTERISTATEID ",16); 
/* get the environment ID from the card 
CSUACFQ( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&verb_data_length, 
verb_data); 
if ( (return_code == OK) | (return_code == WARNING) ) 
{ 
printf("Environment ID was successfully returned.\n"); 
printf("Return/reason codes "); 
printf("%ld/%ld\n\n", return_code, reason_code); 
printf("ID = %.16s\n", rule array); 
} 
else 
{ 
printf("An error occurred while getting the environment ID.\n"); 
printf("Return/reason codes "); 


printf("%ld/%ld\n\n", return_code, reason_code); 


/* return(ERROR) */; 
} 


/* set count to number of bytes of returned data 
rule_array_count = 2; 


return_code 
reason_code 


0; 
0 


/* set keywords in the rule array 
memcpy (rule_array2, "ADAPTER1TIMEDATE", 16) ; 
/* get the time from the card 
CSUACFQ( &return_code, 
&reason_code, 


&exit_data_length, 
exit_data, 
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*/ 


pri 


pr 


pri 


pr 
pr 
pr 


pr 
pr 
pr 
re 


} 


Example: Requesting information from your 4758 Coprocessor 


&rule_array_count, 
(char *)rule_array2, 
&verb_data_length, 
verb_data); 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 


ntf("Time and date was successfully returned. \n"); 
intf("Return/reason codes "); 

ntf("%ld/%ld\n\n", return_code, reason_code); 

intf ("DATE = %.8s\n", rule_array2); 

intf("TIME = %.8s\n", &rule_array2[1]); 

ane of WEEK = %.8s\n", &rule_array2[2]); 

else 

intf("An error occurred while getting the time and date.\n"); 
intf("Return/reason codes "); 

intf("%ld/%ld\n\n", return_code, reason_code); 
turn(ERROR) ; 


Change this program example to suit your needs for requesting information from your 4758 Coprocessor. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Query the 4758 card for status or other information. 
This sample program prompts the user for the second required 
keyword. (ADAPTER1 keyword is assumed.) 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 */ 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these program. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: This verb is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: 
char * keyword2 upto 8 bytes 


Example: 
CALL PGM(CFQ) TIMEDATE 


Note: This program assumes the device to use is 
already identified either by defaulting to the CRPO1 
device or by being explicitly named using the 
Cryptographic_Resource Allocate verb. Also this 
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/* device must be varied on and you must be authorized 
/* to use this device description. 

/* 

/* Use these commands to compile this program on iSeries: 
/* ADDLIBLE LIB(QCCA) 

/* CRTCMOD MODULE(CFQ) SRCFILE(SAMPLE) 

/* CRTPGM PGM(CFQ) MODULE(CFQ) BNDSRVPGM(QCCA/CSUACFQ) 

/* 

/* Note: Authority to the CSUACFQ service program in the 

/* QCCA library is assumed. 

/* 

/* The Common Cryptographic Architecture (CCA) verb used is 
/* Cryptographic_Facility_Query (CSUACFQ). 

/* 


#include "csucincl.h" /* header file for CCA Cryptographic 
/* Service Provider for iSeries 

#include <stdio.h> 

#include <string.h> 

#include <stdlib.h> 


peoceteseeeasessessasosseeses sess esssessss ase aSeeessesese=sSasesses 
/* standard return codes 
[eeseesenees cee seetseesseesSebsece ssa dee cee se ceae acess oecoeoesese 
#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


[ee Snel eteeseeeecesse sa eees acest ose see see Sessa eee lee ees see 
/* standard CCA parameters 

[RSet eames SeGeneaeesace ses neees senses 55 oes ee Se SaaS te a =e a seas 
long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 


char exit_data[4]; 
char rule_array[18] [8]; 
long rule_array_count = 2; 


[eee eesesebe se sseseensenteseenesasencesoees sesso eac eae ope ce etesee 


long verb_data_length = 0; /* currently not used by this verb 
char * verb data = " "3; 


int i; 

/* check the keyboard input 

if (argc != 2) 
sarin did not enter the keyword parameter.\n"); 
printf("Enter one of the following: STATCCA, STATCARD, "); 
printf("STATDIAG, STATEXPT, STATMOFN, STATEID, TIMEDATE\n") ; 


return (ERROR) ; 
} 
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*/ 
*/ 


*/ 
*/ 


if ( (strlen(argv[1]) > 8) | (strlen(argv[1]) < 7) ) 
printf("Your input string is not the right length.\n"); 
printf("Input keyword must be 7 or 8 characters.\n"); 
printf("Enter one of the following: STATCCA, STATCARD, "); 
printf("STATDIAG, STATEXPT, STATMOFN, STATEID, TIMEDATE\n") ; 


return(ERROR) ; 
} 


/* set keywords in the rule array x/ 
memcpy (rule_array, "ADAPTER1 ",16); 
memcpy (&rule_array[1], argv[1], strlen(argv[1])); 
/* get the requested data from the card */ 
CSUACFQ( &return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

(char *)rule_array, 

&verb_data_length, 

verb_data); 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 


printf("Requested data was successfully returned.\n"); 
printf("Return/reason codes "); 
printf ("%ld/%ld\n\n", return_code, reason_code); 
printf("%s data = ", argv[1]); 
for (i = 0; i < 8 * rule_array_count; i 
printf("%c", rule_array[i / 8][i % 8]); 

printf("\n"); 

} 

else 

{ 
printf("An error occurred while getting the requested data.\n"); 
printf("You requested %s\n", argv[1]); 
printf ("Return/reason codes "); 


printf ("%ld/%ld\n\n", return_code, reason_code); 


return(ERROR) ; 
} 


} 


Initialize a key store file 


A key store file is a database file that stores operational keys, i.e. keys encrypted under the master key. 
You can initialize two different types of key stores for your 4758 Coprocessor. The 4758 Coprocessor uses 
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one type to store PKA keys and the other to store DES keys. You need to initialize a key store file if you 
plan to store keys in it or if you plan to use retain keys on hardware. 


The CCA CSP creates a DB2® key store file, if one does not already exist. If a key store file already 
exists, the CCA CSP deletes the file and recreates a new one. 


To initialize a key store, you can use the 4758 Cryptographic Coprocessor configuration utility. Click on 
Manage configuration and then click on either DES keys or PKA keys depending upon what key store 
file you wish to initialize. With the utility, you can only initialize a file if it does not already exist. 


If you would rather write your own application to initialize a key store file, you can do so by using the 
KeyStore_Initialize (CSNBKSI) API verb. Two example programs are provided for your consideration. One 
of them is written in ILE C, while the other is written in ILE RPG. Both perform the same function. 


“Example: ILE C program for initializing a key store for your 4758 Coprocessor” 
“Example: ILE RPG program for initializing a key store for your 4758 Coprocessor” on page 142 


Note: If you choose to use one of the program examples provided, change it to suit your specific needs. 
For security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


After you create a key store for your 4758 Coprocessor, you can generate DES and PKA keys using 
“Create DES and PKA keys” on page 145}to store in your key store files. 

Example: ILE C program for initializing a key store for your 4758 Coprocessor 
Change this program example to suit your needs for initializing a key store for your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
*/ 


| Heseceatesssessessesessasscssessaaseee eas satcsaseeseeesscessouss 

/* Create key store files for PKA keys. */ 
/* */ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999, 2000 x/ 
/* x/ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot x/ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* */ 
/* Parameters: */ 
/* Qualified File Name x/ 
/* */ 
/* Examples: */ 
/* CALL PGM(INZPKEYST) PARM('QGPL/PKAFILE') */ 
/* */ 
/* x/ 
/* Use the following commands to compile this program: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(INZPKEYST) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(INZPKEYST) MODULE(INZPKEYST) + */ 
/* BNDSRVPGM(QCCA/CSNBKS1I) */ 
/* x/ 
/* Note: authority to the CSNBKSI service program in the x/ 
/* QCCA library is assumed. */ 
/* */ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Keystore Initialize (CSNBKSI) x*/ 
/* */ 
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#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 


int main(int argc, char *argv[]) 


{ 
| ee te */ 
/* standard return codes */ 
| ee ee ee eee ee eee ee «/ 


#define ERROR -1 
#define OK 0 


J eoset ssesen sesscesseasuseusasesssssssssssesc Secs eessfsecs seessecsas */ 
/* standard CCA parameters */ 
[Rootes eee see ee eeeseece cece tele eee a SoReal eee ese cee */ 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
char rule_array[4] [8]; 
long rule_array_count; 


| ee ee ee ee eee oe ee ee ee ee */ 
/* fields unique to this sample program */ 
| ee et */ 


long file_name_length; 
unsigned char description[4]; 
long description_length = 0; 
unsigned char masterkey[8]; 


[toseeacesceseesecs sor ese sa eee ea — = eee eo a 4 s= ea esas ease eaae */ 
/* Check if file name was passed */ 
/ $a Seesesase ces aee es eesea seca set ate ence ese eecet er eee */ 


if(argc < 2) 
{ 


printf("File name was not specified.\n"); 
return ERROR; 


} 
(PesssseesnssesacssasecseenssseseoeasesssesscsssSsesSersessesesessoss */ 
/* fill in parameters for Keystore Initialize x/ 
[deenseeseoSeseeeassae sees ese essee ees seeeeeeee ese oats eee eee sree */ 
rule_array_count = 2; 
memcpy ((char*)rule_array,"CURRENT PKA " 16) 
file_name_length = strlen(argv[1]); 
[RSees SeSe eerste aeseeeee ese Seseese eee oseesecessesee See eeeeensesseaS */ 
/* Create key store file */ 
| eee ee ee ee eee eee ee ee */ 
CSNBKSI(&return_code, 
&reason_code, 
&exit_data_length, 


exit_data, 
&rule_array_count, 
(char*) rule_array, 
&file_name_length, 
argv[1], 
&description_length, 
description, 
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masterkey) ; 


[#esesssess fas seeseaseeeensasssseeasenesasesssestensteesseeosiscse sess */ 
/* Check the return code and display the result */ 
Jee desdesesaas see acSsce see se soe neae eee a= Ss =Ss aese see ae eee See as */ 


if (return_code != 0) 


printf("Request failed with return/reason codes: %d/%d\n", 
return_code, reason_code); 
return ERROR; 
} 


else 


printf("Key store file created\n"); 
return OK; 

} 

} 


Example: ILE RPG program for initializing a key store for your 4758 Coprocessor 
Change this program example to suit your needs for initializing a key store for your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DAK RKK KARR KKK ERK KKK KKK KER KKK KEK KER KEK KERR KKK KER KK RRR KERR ERR KEKE R KE 
D* INZPKAST 

Dx« 

D*x Create key store files for PKA keys. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: None 

Dx 

D* Example: 

D* CALL PGM(INZPKEYST) ('QGPL/PKAKEYS') 

Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(INZPKAST) SRCFILE(SAMPLE) 
D* CRTPGM PGM(INZPKEYST) MODULE(INZPKEYST) 


D« BNDSRVPGM(QCCA/CSNBKSI) 

Dx« 

D* Note: Authority to the CSNBKSI service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Key Store Initialize (CSNBKS1) 


* 

eat yet ou se eee 
P¥Seesees see e sce eee e senses see sees esceseesee eee cee 

Dx Declare variables for CCA SAPI calls 

ee eee ee 

Dx ** Return code 
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DRETURNCODE S 9B 0 


D« ** Reason code 
DREASONCODE S 9B 0 
Dx ** Exit data length 
DEXTTDATALEN S 9B 0 
Dx xx Exit data 
DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 
Dx ** Rule array 
DRULEARRAY S 16 

Dx ** File name length 
DFILENAMELEN S 9B 0 
Dx *x File name 
DFILENAME 5 21 

Dx ** Description length 
DDESCRIPLEN S 9B 0 
Dx ** Description 
DDESCRIP S 16 

D* xx Master key part 
DMASTERKEY 5 24 

Dx 


DA RRKK KAKA KKK KKK KK ERK KK ERK KKK KKK KK R KEK KERR KKK RE RK REKR KKK ERK 


D* Prototype for Key Store Initialize (CSNBKSI) 


DA KRKKKKKK KK KKK KKK ERK KK KERR KKK KEK K KER KEK KERR KKK KER KEK RRR KK KERR 


DCSNBKSI PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DFILENMLN 9B 0 

DFILENM 21 

DDSCPLN 9B 0 

DDSCRP 16 

DMSTRKY 24 

Dx« 
DPkeeeseeeesosSceecee cess eo secssoessseescscesscsceSeslesssesssece 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 
DxSecceesesessceeesecoeeslelSSec sec eee wales sesee ose sSes loess se 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 4l 44 

DFATLRSNC 46 49 

DMESSAGEID S 7 INZ(' ) 
DMESSAGEFTLE S 21 INZ(' ry 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx« 

CR KKK KKK KEK KKK KKK KR EKER KER ERK KK EKER RRR ER RRR EKER KERR EKER KERR ERE RR 
Cx START OF PROGRAM * 
CR KKK KKK KKK KKK KKK RE KEK KEK ERK KKK KER KKK RK KERR EKER KERR ERE RE REK ERR ERE 
C *ENTRY PLIST 

C PARM FILENAME 
Ckeaseseeeeceeeseiececeesceekeoseee eee Sse ete ecicee ease se cesses e * 
Cx Set the keyword in the rule array * 
CkaSseeleecee se So aSe Sena seeSsoae Se seas Se sa eee Seea =o s—- see * 
C MOVEL "PKA ; RULEARRAY 
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C MOVE "CURRENT ' RULEARRAY 


C Z-ADD 2 RULEARRAYCNT 

(Reese eeeee se eedeseeeee ese ace reese see shee sees eee nee ene secs * 
Cx Set the description length * 
(keane eee Seti ew ee eee ee eee ee eee ee ee ees * 
C Z-ADD 0 DESCRIPLEN 

Ckeesseesees cose seus suse eeee sede sen eee eee teeeees * 
Cx Find the file name length * 
(kee eee cece esos sere eee eee ees eee eee eee eee esses * 
C EVAL FILENAMELEN = %LEN(%TRIM(FILENAME) ) 
CR K KKK KKK KKK KK KEKE KKK KEK KKK ERE KK KEK EKER RRR KERR ER ERK RR ERE REE KERR ERE 
Cx Call Key Store Initialize SAPI * 
CR KKK KK KEKE KKK KKK KKK EKER KER ERE KKK KER KERR EK ERR ERE RE RR ERE RE RR ERR ERE 
C CALLP CSNBKSI (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

Cc RULEARRAYCNT : 

C RULEARRAY : 

C FILENAMELEN: 

C FILENAME: 

C DESCRIPLEN: 

C DESCRIP: 

C MASTERKEY) 

C# Weeee eee eee eee eee wee * 

Cx * Check the return code * 

CX #eeseeesseseesssussessene * 

C RETURNCODE IFGT 4 

Cx Feeeeeseeeeseeseseessees * 

Cx * Send failure message * 

Cx Peeh Ree ee Sees eee eeeeees * 

C MOVEL MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 

Cx Reeeseceesseseeseseeeses * 

Cx * Send success message * 

Cx Keeose eee eceeeneesessse * 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C SETON 

Cx 


CR KKK KKK KKK KK KEKE KR KK ERK KK EKER KKK EK KEK KEKE KR ERE RRR KEKE REE ERR ERE 


Cx Subroutine to send a message 
CRRA KK KEKE KKK KEKE KK KK ERK EKER ERK RK EKER KEK ERR ERE RE RR ERE RE RK EERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

¢ PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

¢ PARM ERRCODE 

C ENDSR 


K* 
CSNBKSI failed with return/reason codes 9999/9999. 
The file was succesully initialized. 
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Create DES and PKA keys 


You can use your 4758 Coprocessor to create two types of cryptographic keys. 
¢ Data Encryption Standard (DES) keys base their content on a symmetric algorithm. This means that 


cryptography uses the same key value to encrypt and decrypt data. Use DES keys for |“Encrypt or 
decrypt a file” on page 151} |“Work with PINs” on page 157} and managing keys. 

To create DES keys with your 4758 Coprocessor, write a program or change this program 
Creating a DES key with your 4758 Coprocessor” 

* Public key algorithm (PKA) keys base their content on an asymmetric algorithm, meaning that 
cryptography uses different keys for encryption and decryption. Use PKA keys for signing files using 
“Generate and verify a digital signature” on page 170}and for managing keys. 

To create PKA keys with your 4758 Coprocessor, write a program or change this|“Example: Creating a 
PKA key with your 4758 Coprocessor’ on page 148 
Note: If you choose to use the program examples provided, change them to suit your specific needs. For 


security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Store your DES and PKA keys in the key store file you created for them using|“Initialize a key store file” on 
page 130 139 


You can also store PKA keys in your 4758 Coprocessor. See the 4758 information at 


http://www.ibm.com/security/cryptocards/html/library.shtml for more information on storing your keys in 


the hardware. 


Example: Creating a DES key with your 4758 Coprocessor 
Change this program example to suit your needs for creating a DES key with your 4758 Coprocessor. 


eases eae sassnes essa cosas essere assee se saa e Se aoa eae aoe eees «/ 
/* Generate DES keys in key store. */ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* */ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* */ 
/* Parameters: x/ 
/* char * key label, 1 to 64 characters */ 
/* char * key store name, 1 to 21 characters in form 'lib/file' */ 
/* (optional, see second note below) */ 
/* */ 
/* Examples: */ 
/* CALL PGM(KEYGEN) PARM('TEST.LABEL.1') */ 
/* */ 
/* CALL PGM(KEYGEN) PARM('MY.OWN.LABEL' 'QGPL/MYKEYSTORE') x/ 
/* x/ 
/* Note: This program assumes the device you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the x/ 
/* Cryptographic_Resource_ Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. x/ 
/* x/ 
/* If the key store name parameter is not provided, this */ 

/* program assumes the key store file you will use is x/ 
/* already identifed either by being specified on the x*/ 
/* cryptographic device or has been previously named x/ 
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/* using the Key_Store Designate verb. Also you must be */ 


/* authorized to add and update records in this file. x/ 
/* */ 
/* Use the following commands to compile this program: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(KEYGEN) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(KEYGEN) MODULE(KEYGEN) + x/ 
/* BNDSRVPGM(QCCA/CSUAKSD QCCA/CSNBKRC QCCA/CSNBKGN) x/ 
/* */ 
/* Note: authority to the CSUAKSD, CSNBKRC and CSNBKGN service */ 
/* programs in the QCCA library is assumed. x/ 
/* */ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Key Store Designate (CSUAKSD) */ 
/* DES Key Record Create (CSNBKRC) */ 
/* Key Generate (CSNBKGN) */ 
/* */ 
[Rese sseeces as eeesease see esas heseeaSanse ae ase ao aoee ese Secs seeeaee! */ 


#include <stdlib.h> 

#include <stdio.h> 

#include <string.h> 

#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 


int main(int argc, char *argv[]) 


peeseeeaoeeasessessasesseese sss ssesssessas Se seeesescsssees sees ssesas */ 
/* standard return codes */ 
[eesesSseehses seeeeseeseeR ee eHeehe hs os Se aa eee see eee se Sees */ 


#define ERROR -1 
#define OK 0 


[¥eseGSecese oe ct eeesees tee aso Seee ee ee See See Ses ese see eet eeeeSsee eS */ 
/* standard CCA parameters x/ 
ee Se oe ee ee ee ee eee eee oe eee a */ 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
long rule_array_count; 


| ee eT ee eee «/ 
/* fields unique to this sample program */ 
jeedeeseesaseseceesesae sare esse nae eeeessess os —e ae 5 essa eee oe eae e aS */ 


long file_name_length; 
char key_label [64]; 


peedeesecesseesesese see seee essen = esses =Gseas aeaseesacseescsesesees== «/ 
/* See if the user wants to specify which key store file to use */ 
| a te eer */ 


if(argce > 2) 
{ 
file_name_length = strlen(argv[2]); 


if((file_name_length > 0) && 
(file_name_length < 22)) 
{ 


rule_array_count = 1; 


CSUAKSD(&return_code, 
&reason_code, 
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j 


{ 


} 


&exit_data_length, 


exit_data, 
&rule_array_count, 
"DES aa /* rule_array, we are working with 


DES keys in this sample program ~*/ 
&file_name_length, 
argv[2]); /* key store file name x/ 


if (return_code != 0) 


{ 
printf("Key store designate failed for reason %d/%d\n\n", 
return_code, reason code); 
return ERROR; 
} 
else 
{ 
printf("Key store designated\n"); 
printf("SAPI returned %1d/%ld\n", return_code, reason code); 
} 
} 
else 
{ 


printf("Key store file name is wrong length"); 
return ERROR; 


memset(key_label, ' ', 64); 
memcpy(key_label, argv[1], strlen(argv[1])); 


CSNBKRC(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
key_label); 


f (return_code != 0) 


printf("Record could not be added to key store for reason %d/%d\n\n", 


return_code, reason_code); 
return ERROR; 


else 


{ 


printf("Record added to key store\n"); 
printf("SAPI returned %1d/%ld\n", return_code, reason code); 


CSNBKGN(&return_code, 
&reason_code, 
&exit_data_length, 


exit_data, 

POR. 5 /* operational key is requested 
"SINGLE ", /* single length key requested 
"DATA ng /* Data encrypting key requested 


: /* second value must be blanks when 
key form requests only one key */ 


Chapter 5. 4758 Cryptographic Coprocessor for iSeries 


/* let key store file name default */ 


*/ 
*/ 


*/ 
*/ 
*/ 


147 


"\O"" /* key encrypting key is null for 


operational keys */ 
"0", /* key encrypting key is null since 
only one key is being requested */ 
key_label, /* store generated key in key store*/ 
"\O"); /* no second key is requested */ 


if (return_code != 0) 


printf("Key generation failed for reason %d/%d\n\n", 
return_code, reason_code); 

return ERROR; 

} 

else 

{ 
printf("Key generated and stored in key store\n"); 
printf("SAPI returned %1d/%ld\n\n", return_code, reason_code); 
return OK; 

} 

} 


Example: Creating a PKA key with your 4758 Coprocessor 
Change this program example to suit your needs for creating a PKA key with your 4758 Coprocessor. 


[eeboseeee oe aee aera sesedbeese se deae ae deaee eee seamen sce sees ee */ 
/* Generate PKA keys in key store. */ 
/* */ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* */ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* */ 
/* Parameters: x/ 
/* char * key label, 1 to 64 characters */ 
/* */ 
/* Examples: */ 
/* CALL PGM(PKAKEYGEN) PARM('TEST.LABEL.1') x/ 
/* */ 
/* Note: This program assumes the card you want to load is x/ 
/* already identifed either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device descrption. x/ 
/* */ 
/* This program also assumes the key store file you will = */ 
/* use is already identifed either by being specified on */ 
/* the cryptographic device or has been explicitly named = */ 
/* using the Key_Store Designate verb. Also you must be */ 
/* authorized to add and update records in this file. */ 
/* */ 
/* Use the following commands to compile this program: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(PKAKEYGEN) SRCFILE (SAMPLE) */ 
/* CRTPGM PGM(PKAKEYGEN) MODULE(PKAKEYGEN) + x/ 
/* BNDSRVPGM(QCCA/CSNDKRC QCCA/CSNDPKG) x/ 
/* */ 
/* Note: authority to the CSNDKRC and CSNDPKG service programs  */ 
/* in the QCCA library is assumed. x*/ 
/* */ 
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/* Common Cryptographic Architecture (CCA) verbs used: 
/*  PKA_Key Record Create (CSNDKRC) 

/* PKA_Key Generate (CSNDPKG) 

/* 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 

int main(int argc, char *argv[]) 

{ 
[Reece S Seber eesaseee sus ee eS See ee eae see ee eee eee Sees ee seo ceeeens «/ 
/* standard return codes x/ 
[eeeseseseeeesrasaetossee esac eesee sea Sa sere saeco sae eae eee seen ce ssenS */ 
#define ERROR -1 
#define OK 0 
[eset aces sesnseecaesa ser ee arse sa] 6 SSeS eae oa ee eee ee ee eae */ 
/* standard CCA parameters x/ 
| ee ee ee ee ee ee eee «/ 

long return_code; 

long reason_code; 

long exit_data_length; 

char exit_data[2]; 

char rule_array[4] [8]; 

long rule_array_count; 
Jeases seessasesssesteacuscusasssesseasesscesesssSssessscesessscessse ss */ 
/* fields unique to this sample program */ 
[Raereseees ee eeeetseseesSo ete se ece ease sp eeaeeoesee sees eceseeSkeeeae «/ 


char key_label [64]; 
hold generated key */ 
#pragma pack (1) 


typedef struct rsa_key_token_header_section { 
char token_identifier; 
char version; 
short key_token_struct_length; 
char reserved 1[4]; 
} rsa_key_token_header_section; 


typedef struct rsa_private_key_ 1024 bit_section { 
char section_identifier; 
char version; 
short section_length; 
char hash_of_private_key[20]; 
short reserved_1; 
short master_key_verification_pattern; 
char key_format_and_security; 
char reserved 2; 
char hash_of_key_name[20]; 
char key_usage_flag; 
char rest_of_private_key[312]; 
} rsa_private_key 1024 bit_section; 


typedef struct rsa_public_key section { 
char section_identifer; 
char version; 
short section_length; 
short reserved_1; 


/* identify record in key store to 
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short exponent_field_length; 
short modulus_length; 
short modulus_length_in_bytes; 
char exponent; 

} rsa_public_key_ section; 


struct { 
rsa_key_token_header_section rsa_header; 
rsa_private_key_1024 bit_section rsa_private_key; 
rsa_public_key_section rsa_public_key; 


} key_token; 


struct { 
short modlen; 
short modlenfld; 
short pubexplen; 
short prvexplen; 
long pubexp; 

} prvPubl; 


#pragma pack () 
long key_struct_length; 
long zero = 0; 
long key_token_length; 


long regen_data_length; 
long generated_key_id_length; 


[esse seeeehe ce oteeeshe see ete eeese ts oes see Se“ Seeese eee saeco esece ae */ 
/* Create record in key store */ 
jieseeseres aa seesesases serie se ense esse tao S5 55 S44 5ee Saas eee eee eae */ 

rule_array_count = 0; 

key_token_length = 0; 

memset(key_label, ' ', 64); 


memcpy(key_label, argv[1], strlen(argv[1])); 


CSNDKRC(&return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

"\e", /* rule_array */ 
key_label, 

&key_token_length, 

"\O")s /* key token */ 


if (return_code != 0) 


printf("Record could not be added to key store for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; 
} 
else 
{ 
printf("Record added to key store\n"); 
printf("SAPI returned %1d/%ld\n", return_code, reason_code) ; 


[Retake eaees see Ses ees oes eee se eee eee eee aes ees ese sees aaa eae eas */ 
/* Build a key token, needed to generate PKA key */ 
[eesecscecenesaehesereesewe asses o asec seeses este senses eesseeesso55 */ 


memset (&key_token, 0X00, sizeof (key_token)); 


key_token.rsa_header.token_identifier = OX1E; /* external token  */ 
key_token.rsa_header.key_token_struct_length = sizeof(key_token); 
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key_token.rsa_private_key.section_identifier = 


0x02; /* RSA private key */ 


key_token.rsa_private_key.section_length = 


sizeof(rsa_private_key 1024 bit_section); 


key_token.rsa_private_key.key_usage flag = 0X80; 


key_token.rsa_public_key.section_identifer = 0X04; /* RSA public key */ 
key_token.rsa_public_key.section_length = 


sizeof (rsa_public_key section); 


key_token.rsa_public_key.exponent_field_length = 1; 
key_token.rsa_public_key.modulus_length = 512; 
key_token.rsa_public_key.exponent = 0x03; 


key_token_length = sizeof (key_token) ; 


printf("Key token built\n"); 


| eee ee eee ee «/ 
/* Generate a key */ 
[#oseeseeeeteeese Sele eee eee Sosa eee eS oe ces eeeee */ 


} 


rule_array_count = 1; 
regen_data_length = 0; 


/* key_token_length = 64; */ 
generated_key_id_length = 2500; 
CSNDPKG(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
"MASTER ", /* rule_array */ 
&regen_data_length, 
"\O", /* regeneration_data, none needed */ 
&key_token_length, /* skeleton_key_token_length */ 
(char *)&key_token, /* skeleton_key_token built above */ 
"\O", /* transport_id, only needed for 
XPORT keys */ 
&generated_key_id_length, 
key_label); /* generated_key_id, store generated 
key in key store */ 


i 


f (return_code != 0) 


{ 
printf("Key generation failed for reason %d/%d\n\n", 
return_code, reason_code); 
return ERROR; 

} 

else 

{ 


} 


printf("Key generated and stored in key store\n"); 
printf("SAPI returned %1d/%ld\n\n", return_code, reason_code); 
return OK; 


Encrypt or decrypt a file 


One of the more practical uses for your 4758 Coprocessor is encrypting and decrypting data files. You can 
use one of these cryptographic methods to protect a file: 


¢ Treat the whole file as a string of bytes (which is the method the program example uses). 


Encrypt each record or part of each record. 
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to protect data in many different formats, not just data files. 


Write your own program or change the techniques in this program|“Example: Encrypting data with your 
4758 Coprocessor” 


Example: Encrypting data with your 4758 Coprocessor 
Change this program example to suit your needs for encrypting data with your 4758 Coprocessor. 


[xeseescassasa sae soecoesene sass scene nase eesseeesenesnesce nko cee--so5 «/ 
/* x/ 
/* Sample C program for enciphering data in a file. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for x/ 
/* these programs and files. x/ 
/* x/ 
/* Parameters: x/ 
/* char * key label, 1 to 64 characters */ 
/* char * input file name, 1 to 21 characters (lib/file) */ 
/* char * output file name, 1 to 21 characters (lib/file) x/ 
/* x/ 
/* Example: */ 
/* CALL PGM(ENCFILE) PARM( 'MY.KEY.LABEL' 'QGPL/MYDATA' + */ 
/* 'QGPL/CRYPTDATA' ) */ 
/* x/ 
/* Note: This program assumes the device you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the x/ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* x/ 
/* This program assumes the key store file you will use is */ 
/* already identifed either by being specified on the x/ 
/* cryptographic device or has been previously named x/ 
/* using the Key_Store Designate verb. Also you must be x/ 
/* authorized to add and update records in this file. */ 
/* x/ 
/* The output file should NOT have key fields since all */ 
/* data in the file will be encrypted and therefore trying */ 
/* to sort the data will be meaningless. x/ 
/* (This is NOT checked by the program) */ 
/* x/ 
/* Use the following commands to compile this program: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(ENCFILE) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(ENCFILE) MODULE(ENCFILE) + */ 
/* BNDSRVPGM(QCCA/CSNBENC) */ 
/* x/ 
/* Note: authority to the CSNBENC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/*  Encipher (CSNBENC) */ 
/* x/ 
| ee eee */ 
[Reeeesse ses se esses s sete eesSsneas eee ese eeee tessa seeeeeeee sa assae */ 
/* Retrieve various structures/utilities that are used in program. */ 
JeasecssenscesososesesssedssseesaesecssesesasessSesecekerssesceesscees */ 
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#include <stdio.h> /* Standard 1/0 header. */ 


#include <stdlib.h> /* General utilities. x/ 
#include <stddef.h> /* Standard definitions. x/ 
#include <string.h> /* String handling utilities. x/ 
#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 
Jeeses seasoassessestesSouecessaSse cs sete sseesessesteseseesacscessaases */ 
/* Declares for working with files. x*/ 
Jetees acess susgssseseoue odscsescescseessesseSecsnsssesssssessssssoss */ 
#include <xxfdbk.h> /* Feedback area structures. */ 
#include <recio.h> /* Record I/0 routines */ 
_RFILE xdbfptr; /* Pointer to database file. */ 
_RFILE xdbfptre; /* Pointer to database file. x/ 
_RIOFB_T xdb_fdbk; /* I/0 Feedback - data base file x/ 
_XXOPFB_T *db_opfb; 
_XXOPFB_T *db_opfbe; 
[eeereSeee eee sess cee eee ete e ee eet sees eee tee ee ceseeSeeeeas */ 
/* Declares for working with user space objects. x/ 
PP eeees aces asene secs esses reee eee aes Se seceese esas aeeesaoe see =e =o oe ae */ 


#include "qusptrus.h" 
#include "quscrtus.h" 
#include "qusdltus.h" 


#define USSPC_ATTR "PF " 
#define USSPC_INIT_VAL 0x40 
#define USSPC_AUTH "*EXCLUDE " 
#define USSPC_TEXT "Sample user space" 
#define USSPC_REPLACE "*YES " 
char space_name[21] = "PLAINTXT QTEMP "; /* Name of user 
space for plain text */ 
char cipher_name[21] = "CIPHER QTEMP "; /* Name for user 
space containing ciphertext x/ 
struct { /* Error code structure required for */ 
/* the User Space API's. */ 
int in_len; /* the length of the error code. */ 
int out_len; /* the length of the exception data. */ 
char excp_id[7]; /* the Exception ID. */ 
char rev; /* Reserved Field. */ 
char excp_data[120]; /* the output data associated */ 
} error_code; /* the exception ID. */ 
char ext_atr[11] = USSPC_ATTR; /* Space attribute x/ 
char initial_val = USSPC_INIT_VAL; 
/* Space initial value ~*/ 
char auth[11] = USSPC_AUTH; 
/* Space authority */ 
char desc[51] = USSPC_TEXT; 
/* Space text */ 
char replace[11] = USSPC_REPLACE; 

/*Space replace attribute/ 
| ee ee ee ee */ 
/* Start of mainline code. */ 
[fee eeeeseaeeasseaseateses Soe esseeseeseceaetecesseseesseesesensessee5 */ 


J[eeeeeueesanssnssse see esenssossecsees senses Se osenaacesesesereeaseas */ 
/* standard return codes */ 
[fees esetses seeenetee= ssea sesso teees seeds ae eens cee cease cee sese */ 


#define ERROR -1 
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#define OK 0 


[ #eSet Sess Sas see sestesseesessssee Sees sa easeeesheesseeeseeoeiscee sees */ 
/* standard CCA parameters x/ 
[ #ecee see saaes sesesS see sees =a ae eae Ss Ss Se ea eae eas «/ 


long return_code; 
long reason_code; 
long exit_data_length; 
char exit_data[2]; 
long rule_array_count; 


char xuser_space_ptr; 

char xuser_space; 

char *cipher_spc; 

long file_bytes; 

long is 

long J; 

char key_label [64]; 

long text_len, pad_character; 

char initial_vector[8]; 

char chaining_vector[18] ; 
[#ssecceeaesach sess seeseese fossa = Sees sae sas Sos eee ease as */ 
/* Open database files. */ 
[#esehscnescsacaseceseesenes sooo donee eee eee cece ceca «/ 

if (argc < 4) /* were the correct number 


of parameters passed? */ 


printf("This program needs 3 parameters - "); 
printf("key label, input file name, output file name\n"); 


return ERROR; 


} 
else 
{ 
file_bytes = 0; /* Set initial number of 
bytes to encipher to @ «/ 
/* Open the input file. If the file pointer, dbfptr is not 
NULL, then the file was successfully opened. */ 
if (( dbfptr = Ropen(argv[2], "rr riofb=n")) 
!= NULL) 
{ 
[#eseessess cesses sesses se sssesSesseeeesssassessoasoses Sa S Seen Sses— */ 
/* Determine the number of bytes that will be enciphered. */ 
[#eSesssees Ses sensSese ase se a seeeeeseae sae eseee seer neeeeeenseee sess */ 
db_opfb = Ropnfbk( dbfptr );  /* Get pointer to the File 
open feedback area. */ 
file_bytes = db_opfb->num_records * 
db_opfb->pgm_record_len 
#1 /* 1 is added to prevent an 
end of space error */ 
j = db_opfb->num_records; /* Save number of records*/ 
[kssesesseesesstesesea esse secesHessesseeseeeseeeserecseseeesesccee «/ 
/* Create user space and get pointer to it. x/ 
( Radeeeeesaas see ses see seca tesa measeaes aes Hao SeasesSacaeseaseecss< */ 
error_code.in_len = 136; /* Set length of error */ 
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/* structure. */ 
QUSDLTUS(space_name,&error_code); /* Delete the user space 
if it already exists. */ 


/* Create the plaintext user space object */ 
QUSCRTUS (space_name,ext_atr,file bytes, 
&initial_val,auth, 
desc, replace,&error_code) ; 


error_code.in_len = 48; /* Set length of error 
structure x/ 
QUSPTRUS (space_name, /* Retrieve a pointer to */ 
(void *)&user_space, /* the user space. */ 


(char*) &error_code) ; 


user_Space_ptr = user_space; /* Make copy of pointer +*/ 


error_code.in_len = 136; /* Set length of error */ 
/* structure. x/ 

QUSDLTUS (cipher_name, &error_code) ; /* Delete cipher space 
if already exists. */ 


/* Create ciphertext user space object */ 
QUSCRTUS (cipher_name,ext_atr, 
file_bytes,&initial_val,auth, 
desc, replace,&error_code) ; 


error_code.in_len = 48; /* Set length of error */ 
/* structure x/ 
QUSPTRUS (cipher_name, /* Retrieve pointer to */ 


(void *)&cipher_spc, /* ciphertext user space */ 
(char*) &error_code) ; 


/#eeeteetsece ssaeheaseceen seen se eeeeheosseeeeesaeaceene essence sess «/ 
/* Read file and fill space */ 
[eeeeeateasassesnetesececcetenseossesseesreeces aeons oeeeseseeeecas «/ 
for (i=1; i<=j; i++) /* Repeat for each record */ 

{ 
/* Read a record and place in user space. */ 


db_fdbk = Rreadn(dbfptr, user_space_ ptr, 
db_opfb->pgm_record_len, _ DFT); 


/* Move the user space ahead the length of a record */ 
user_Space_ptr = user_space_ptr + 
db_opfb->pgm_record_len; 


} 


if (dbfptr != NULL) /* Close the file. */ 
_Rclose(dbfptr) ; 

[easecbSeesseessSeeecet ese esateee eee ee ates cane teste ce senseless «/ 
/* Encrypt data in space */ 
[eeceeeaeseasseseseseeras eas ees=sesesseese see csers aasees=cS=ssoese «/ 
memset ((char *)key_label,' ',64);  /* Initialize key label 

to all blanks. x/ 

memcpy((char *)key_label, /* Copy key label parm */ 


argv[1],strlen(argv[1])); 


text_len = file_bytes - 1; 
rule_array_count = 1; 

pad_character = 40; 

exit_data_length = 0; 
memset ((char *)initial_vector,'\0',8); 


/* Encipher data in ciphertext user space x/ 
CSNBENC(&return_code, 
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&reason_code, 
&exit_data_length, 
exit_data, 
key_label, 
&text_len, 
user_space, 
initial_vector, 
&rule_array_count, 
"CBC a /* rule_array */ 
&pad_character, 
chaining_vector, 
cipher_spc ); 


if (return_code == 0) { 


[ Betareeacsacssesses seesesec ceaisees aes =S5 Sos Sees esos so —— Ss aese5 */ 
/* Open output file */ 
[ReeeaSecesnes-senessaseeneseassscesssess se sesansedensseccsseencse «/ 


if (( dbfptre = Ropen(argv[3], 
"wr riofb=n")) != NULL) 


db_opfbe = Ropnfbk( dbfptr ); /* Get pointer to 
the File open feedback 


area. */ 
if(text_len % db _opfbe->pgm_record_len != 0) 
{ 
printf("encrypted data will not fit into "); 
printf("an even number of records\n"); 
if (dbfptre != NULL) /* Close the file. x/ 
_Rclose(dbfptre) ; 
| eee ee «/ 
/* Delete both user spaces. x/ 
[#eeeesessessoessosssessssoescesesesesessceess «/ 
error_code.in_len = 136; /* Set length of 
error structure. */ 
QUSDLTUS (space_name,&error_code); /* Delete the 
user space */ 
QUSDLTUS (cipher_name, &error_code); /* Delete 
ciphertext space */ 
return ERROR; 

} 
[Reseebenaseseetesteceesr ee desseseqesceeesheitste sees te aeseas=n=5 «/ 
/* Write data from space to file. x/ 
/#eseetsoassesece scenes sesacscesseseesessessescescaeesoesecesccecs */ 

user_space ptr = cipher_spc; /* Save pointer to 


cipher space. x/ 


j = text_len / db_opfbe->pgm_record_len; /* find 
how many records 
are needed to store 
result in output 


file x/ 
for (i=1; i<=j; i++) /*x Repeat for each 
record x/ 
{ 
/* Write data to output file */ 
db_fdbk = Rwrite(dbfptre, user_space_ptr, 
db_opfbe->pgm_record_len); 
/* Advance pointer ahead the length of a record */ 
user_space_ptr = user_space_ptr + 
db_opfbe->pgm_record_len; 
} 
if (dbfptre != NULL) /* Close the file */ 
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_Rclose(dbfptre) ; 


} 


else 


/* end of open open 
output file x/ 


printf("Output file %s could not be opened\n", 


argv[3]); 
[Roecee soeeeacsacsseesesseeseceass=sSsesseseee «/ 
/* Delete both user spaces. x/ 
PResse psoas toesesaaas seeseneeeasel cee aeee «/ 
error_code.in_len = 136; /* Set length of 
error structure. */ 
QUSDLTUS(space_name,&error_code); /* Delete the 
user space */ 
QUSDLTUS (cipher_name,&error_code); /* Delete 
ciphertext space */ 
return ERROR; 
} 
} /* If return code = 0 */ 
else 


printf("Bad return/reason code : %d/%d \n", 


return_code, reason_code) ; 


error_code.in_len = 136; 


/* Set length of 
error structure. */ 


QUSDLTUS (space_name,&error_code); /* Delete the 


user space */ 


QUSDLTUS (cipher_name, &error_code); /* Delete 


return ERROR; 


ciphertext space */ 


J eessassasesseses sa suaeswsnsssssssasessaas- ss SSseeSsssses sessSese ee «/ 
/* Delete both user spaces. x*/ 
[eoseeeeedseecseseesees eee tees eeeecsee ptaeee ae eeae stee ce see ee eee «/ 
error_code.in_len = 136; /* Set length of 
error structure. */ 
QUSDLTUS (space_name, &error_code) ; /* Delete the user 
space */ 
QUSDLTUS (cipher_name, &error_code) ; /* Delete ciphertext 
space */ 
} /* End of open 
input file x/ 
else 
{ 
printf("Input file %s could not be opened\n", argv[2]); 
return ERROR; 
} 
} /* argv[] == null */ 
return OK; 


} 
Work with PINs 


A financial institution uses personal identification numbers (PINs) to authorize personal financial 
transactions for its customers. A PIN is similar to a password except that a PIN consists of decimal digits 
and is normally a cryptographic function of an associated account number. You can use your 4758 


Coprocessor to work with PINs. 
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To work with PINs, write a program or change this program|“Example: Working with PINs on your 4758 


Note: If you choose to use the program example provided, change it to suit your specific needs. For 
security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Example: Working with PINs on your 4758 Coprocessor 
Change this program example to suit your needs for working with PINs on your 4758 Coprocessor. 


FR KK AKKK KEKE KKK KK KK KERR KEKE KEKE RRR RK RRR KK EKER KEKE RRR RR ERE KK ER ERE 
F* PINSAMPLE 
Fx 
Fx Sample program that shows the use of the appropriate 
Fx CCA Security API (SAPI) verbs for generating and verifying 
Fx PINS 
Fx 
Fx The keys are created by first building a key token 
Fx and then importing key parts using Key _Part_Import. 
Fx Four keys are created each with a different 
Fx key type - PINGEN, PINVER, IPINENC, and OPINENC. The 
Fx PINGEN key will be used to generate a Clear PIN with the 
Fx Clear_PIN Generate verb. The OPINENC key will be used 
Fx to encrypt the PIN with the Clear_PIN Encrypt verb. 
Fx The Encrypted_PIN Verify with verify that the PIN is good 
Fx using the IPINENC key (to decrypt) and the PINVER key 
Fx to verify the PIN. 
Fx 
Fx COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 
Fx 
Fx This material contains programming source code for your 
Fx consideration. These example has not been thoroughly 
Fx tested under all conditions. IBM, therefore, cannot 
Fx guarantee or imply reliability, serviceability, or function 
Fx of these programs. All programs contained herein are 
Fx provided to you "AS IS". THE IMPLIED WARRANTIES OF 
F* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
F* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
Fx these programs and files. 


Fx 

Fx 

Fx Note: Input format is more fully described in Chapter 2 of 
Fx IBM 4758 CCA Basic Services Reference and Guide 
Fx (SC31-8609) publication. 

Fx 

Fx Parameters: 

F* none. 

Fx 

Fx Example: 

Fx CALL PGM(PINSAMPLE) 

Fx 


Fx Use these commands to compile this program on iSeries: 
Fx CRTRPGMOD MODULE(PINSAMPLE) SRCFILE (SAMPLE) 
Fx CRTPGM PGM(PINSAMPLE) MODULE(PINSAMPLE) 


Fx BNDSRVPGM(QCCA/CSNBKPI QCCA/CSNBPGN + 

Fx QCCA/CSNBCPE QCCA/CSNBPVR) 

Fx 

Fx Note: Authority to the CSNBKPI, CSNBPGN, CSNBCPE, and 

Fx CSNBPVR service programs in the QCCA library is assumed. 
Fx 


F* The Common Cryptographic Architecture (CCA) verbs used are 
Fx Key Part_Import (CSNBKPI), Clear_PIN Generate (CSNBPGN) , 
Fx Clear_PIN Encrypt (CSNBCPE), and Encrypted_PIN Verify (CSNBPVR). 


Fx 
Fx Note: This program assumes the card you want to load is 
Fx already identifed either by defaulting to the CRPO1 
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Fx device or has been explicitly named using the 


Fx Cryptographic_Resource Allocate verb. Also this 

Fx device must be varied on and you must be authorized 
Fx to use this device descrption. 

Fx 


FRKKK KKK KKK KK KKK KK KER KK KEK KK KERR KKK ERK KR KER KR ERK KER KEK KR RRR RRERE 
Fx Declare parameters that are common to all of the CCA verbs 
Fx 


FARK KK KKK KKK KK KK KKK KER KKK ERK KKK RR KK RRR KKK KER KEKE RE K RE RKE KEKE RRERE 


DRETURNCODE S 9B 0 
DREASONCODE S 9B 0 
DEXITDATALEN S 9B 0 
DEXITDATA S 4 
DRULEARRAYCNT S 9B 0 
DRULEARRAY S 16 

Dx« 


DA KRKK KKK KKK KEK KKK ERK KK ERK KKK KERR KER KERR RRR RRR ERR RRR RRR ERR ERR RERER 
D* Declare Key tokens used by this program 


Dx« 

DAK KKK KAKA KKK KK KKK KEK KKK KEK KEKE KKK KEK KKK EKER KER KEE EKER ER ERRERER 
DIPINKEY 5 64 
DOPINKEY S 64 
DPINGENKEY S 64 
DPINVERKEY S 64 
DKEYTOKEN DS 

DKEYFORM 1 1 
DKEYVERSION 5 5 
DKEYFLAG1 7 7 
DKEYVALUE 17 32 
DKEYCV 33 48 
DKEYTVV 61 64B 0 
DTOKENPART1 1 16 
DTOKENPART2 17 32 
DTOKENPART3 33 48 
DTOKENPART4 49 64 
DKEYTVV1 1 4B 0 
DKEYTVV2 5 8B 0 
DKEYTVV3 9 12B 0 
DKEYTVV4 13 16B 0 
DKEYTVV5 17 20B 0 
DKEYTVV6 21 24B 0 
DKEYTVV7 25 28B 0 
DKEYTVV8 29 32B 0 
DKEYTVV9 33 36B 0 
DKEYTVV10 37 40B 0 
DKEYTVV11 41 44B 0 
DKEYTVV12 45 48B 0 
DKEYTVV13 49 52B 0 
DKEYTVV14 53 56B 0 
DKEYTVV15 57 60B 0 
Dx« 


DA KRKKKKKK KKK KEK KKK ERK KK ERK KKK KKK KK R KK RK E KKK RE RK RRR KKK RRR RRERER 
D* Declare parameters unique to Key _Part_Import 


Dx« 

DARA KAKA KEK KK KEK KKK KKK EKER KERR EKER KER KEK ER ERR ERK ER ERR ER ERRERER 
DCLEARKEY S 16 

Dx« 


DA KRKKKKKK KKK KKK KKK KKK ERK KKK KKK KKK KEK KERR KEK KR ER KERR ERK KEE RRR RRR 


D* Declare parameters unique to Clear_PIN Generate, 
D* Clear_PIN Encrypt, and Encrypted_PIN Verify 


DA KRK KK KK KKK KEK KKK ERK KK ERK KKK KKK KKK KK KEKE KK KR ERR RRR KEKE ERK RRR 


DPINLEN Ss 9B 0 
DPINCKL S 9B 0 
DSEQNUMBER Ss 9B 0 
DCPIN S 16 
DEPIN S 16 
DPAN S 12 
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DDATAARRAY DS 
DDECTABLE 

DVALDATA 

DCLRPIN 

DPROFILE DS 
DPINFORMAT 
DFORMATCONTROL 
DPADDIGIT 

Dx« 


16 
32 
48 


8 
16 
24 


DAR RAKKKKKKK KER KKK KKK KK ERK KKK ERK KK ERK KERR KKK KER KEK KERR KK RRR RR RERERE 
D* Declare variables used for creating a control vector and 


D* clear key. 


DA RRAKK KK KKK KERR KEKE KKK KERR KERR RK KR RRR ERE RK KR ER RRR ER KEK RE RRRERRRERER 


DBLDKEY DS 
DLEFTHALF 

DLEFTHALFA 
DLEFTHALFB 
DRIGHTHALF 

Dx« 

Dx« 


1 
i 
5 
9 


8 
4B 0 
8B 0 
16 


DA KRAKKKK KKK KEK KK KEK KK KERR KK RR EK KR ERR RR ERR RRR KER RERA 


D* Prototype for Key Part Import (CSNBKPI) 


DARK KK KAKA KKK ERK KK EK KKK RRR KR E KKK KERR KK ERK KR KER EKER 


DCSNBKPI PR 
DRETCODE 

DRSNCODE 

DEXTDTALEN 

DEXTDTA 

DRARRAYCT 

DRARRAY 

DCLRKEY 

DIMPKEY 

Dx 


DARK KK KKKK KKK ERK KK EK KKK KERR KEKE RK KK ERR RK ERK KR KERR KEKE RE 


D* Prototype for Clear PIN Generate (CSNBPGN) 


DA KRAKKKKKK KK ERK KKE KKK KERR KERR KEK KR ERE RRR R KERR ERR RRR 


DCSNBPGN PR 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DPINGEN 
DRARRAYCT 
DRARRAY 
DPINL 
DPINCHKLEN 
DDTAARRY 
DRESULT 

Dx« 


9B 0 
9B 0 
9B 0 


DA KRRKKKK KKK KER KKK KKK KEKE RR KERR KEK RRR RRR RRR KR REE KER 


D* Prototype for Clear PIN Encrypt (CSNBCPE) 


DA KRAKK KKK KK KEK KKK EK KKK RRR KEKE KEK KR ERR RRR KEK KR KERR KEK REER 


DCSNBCPE PR 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DPINENC 
DRARRAYCT 
DRARRAY 
DCLRPIN 
DPINPROFILE 
DPANDATA 
DSEQN 
DEPINBLCK 
Dx« 


9B 0 
9B 0 


DA KRRKKKKK KKK ERK KK EK KKK ERK KK ERK KK KERR RRR KEK KR KERRKKRR RK 
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Dx Prototype for Encrypted PIN Verify (CSNBPVR) 


DA KRKKKKKKK KK KEK KKK KEK K KK R KEKE RRR KKK ERK KR ERK RR ERER EKER 


DCSNBPVR PR 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DPINENC 
DPINVER 
DPINPROFILE 
DPANDATA 
DEPINBLCK 
DRARRAYCT 
DRARRAY 
DCHECKLEN 
DDTAARRAY 
Dx« 


DA KRKKKKKKK KK KEK KKK ERK KK ERR KERR RRR KERR RRR RRR RRR RRR RRR RE ERERERRRER 


9B 0 
9B 0 
9B 0 
4 
64 
64 
24 
12 
8 
9B 0 
16 
9B 0 
24 


Dx Declares for sending messages to job log 


DA KRKKKKKK KKK KK KK KEK KKK ERK KKK KKK KKK KEK KKK KEK KR ER KERR KKK RRR RRR 


DFAILMESSAGE S 50 

DGOODMESSAGE S 50 

DFAILMSG DS 

DFAILMSGTEXT 1 50 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DRETSTRUCT DS 

DRETCODE 1 41 0 

DSLASH 5 5 INZ('/') 

DRSNCODE 6 9I 0 

DFAILMSGLENGTH S 9B @ INZ(49) 

DGOODMSGLENGTH S 9B @ INZ(29) 

DMESSAGEID S 7 INZ(' ') 

DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' Kr) 

DMSGTYPE S 10 INZ('*INFO 

DSTACKENTRY S 10 INZ('* 

DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B © INZ(0) 

C EVAL FAILMESSAGE = '***xx**x* failed with return+ 
Cc /reason codes 9999/9999' 
C EVAL GOODMESSAGE = 'PIN Validation was successful’ 
CR KKK KK KKK KK KK KKK KR EKER KER ER KKK RK ERK RR EKER RE KERR RR ERE RR EKRERRE ERE 

Cx START OF PROGRAM * 

Cx * 


CK KKK KKK KKK KKK KKK RE KEK KKK ERK KKK KER KEK KKK KEK ER ERK RR ER ERK RK ERR ERE 
Cx Build a PINGEN key token 

Cx* 

CR K KK KK KKK KKK KEKE KR EKER KER ER KEK KEK ERK RR EK RRR ERE RRR ERE RRR ERR 


Cx Zero out the key token to start with 


Cx* 

C Z-ADD ) KEYTVV1 

C Z-ADD ) KEYTVV2 

C Z-ADD ) KEYTVV3 

C Z-ADD ) KEYTVV4 

C MOVE TOKENPART1 TOKENPART2 
C MOVE TOKENPART1 TOKENPART3 
C MOVE TOKENPART1 TOKENPART4 
Cx« 

Cx Set the form, version, and flag byte 

Cx« 

C BITON oe KEY FORM 

C BITON '67' KEYVERSION 
C BITON YL KEYFLAG1 
Cx« 
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Cx The control vector for a PINGEN key that has the key part 
Cx flag set is (in hex): 

Cx 

Cx 00227E00 03480000 00227E00 03280000 

Cx« 

Cx If each 4 byte hex part is converted to decimal you get: 
Cx 

Cx 2260480 55050240 2260480 52953088 

Cx 

Cx Build the control vector by placing the decimal number in 


Cx the appropriate half of the control vector field. 
CARR KAKA KEK KKK KKK KKK EKER KER ERE KKK ERE RR EKER ER ERE RR ERE REE ERREERE 


C Z-ADD 2260480 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2260480 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

Cx« 


Cx Calculate the Token Validation value by adding every 4 bytes 
C* and storing the result in the last 4 bytes. 


Cx 

C ADD KEYTVV1 KEYTVV 
C ADD KEYTVV2 KEYTVV 
C ADD KEYTVV3 KEYTVV 
C ADD KEYTVV4 KEYTVV 
C ADD KEYTVV5 KEYTVV 
C ADD KEYTVV6 KEYTVV 
C ADD KEYTVV7 KEYTVV 
C ADD KEYTVV8 KEYTVV 
C ADD KEYTVV9 KEYTVV 
C ADD KEYTVV10 KEYTVV 
C ADD KEYTVV11 KEYTVV 
C ADD KEYTVV12 KEYTVV 
C ADD KEYTVV13 KEYTVV 
C ADD KEYTVV14 KEYTVV 
C ADD KEYTVV15 KEYTVV 
Cx« 

Cx Copy token to PINGENKEY 

Cx* 

C MOVE KEYTOKEN PINGENKEY 
Cx« 


CARR KA KKK KKK KK KKK KR KK EK KKK EKER KKK ER KKK RK ERR ERE RK RR EKER ERR EKER 
Cx Build a PINVER key token 

Cx* 

Cx The control vector for a PINVER key that 

Cx has the key part flag set is (in hex): 

Cx 

Cx 00224200 03480000 00224200 03280000 

Cx 

Cx If each 4 byte hex part is converted to decimal you get: 
Cx« 

Cx 2260480 55050240 2260480 52953088 

Cx 

Cx Build the control vector by placing the decimal number in 
Cx the appropriate half of the control vector field. 


C Z-ADD 2245120 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2245120 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

Cx 


Cx Calculate the Token Validation value by adding every 4 bytes 
C* and storing the result in the last 4 bytes. 


C Z-ADD 0 KEYTVV 
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DOA DAAAAOAOAAAOOAl0 74:0 A: 
+ + + 


a 
+ 


ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 


Copy token to PINVERKEY 


MOVE 


KEYTVV1 
KEYTVV2 
KEYTVV3 
KEYTVV4 
KEYTVV5 
KEYTVV6 
KEYTVV7 
KEYTVV8 
KEYTVV9 
KEYTVV10 
KEYTVV11 
KEYTVV12 
KEYTVV13 
KEYTVV14 
KEYTVV15 


KEYTOKEN 


KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 


PINVERKEY 


CR KKK KK KKK KKK KEKE KR EKER KER ER KEK KEK ERK RRR REE REK ERE RR ERE RE RRR RR ERE 


Cx Build an IPINENC key token 


Cx* 
Cx« 
Cx* 
Cx« 
Cx« 
Cx« 
Cx« 
Cx* 
Cx* 
Cx* 


The control vector for an IPINENC key that 
has the key part flag set is (in hex): 


00215FOO 03480000 00215FOO0 03280000 


If each 4 byte hex part is converted to decimal you get: 


2187008 55050240 2187008 


52953088 


CR KKK KK KEK KKK KK KKK KR EKER KEK ERK KK EKER KK KEKE KEKE ERK RR ERE RK RK ERR ERE 
Cx Build the control vector by placing the decimal number in 


Cx the appropriate half of the control vector field. 
CR KKK KK KKK KKK KEKE EKER ERK ER ER KERR RK ERK RR EKER EKR ERE RR EKER EKERRE ERE 


a 


CQ OF OOD OF: OI HOO OOOO. 


Cx* 
Cx* 
Cx« 
C 


Z-ADD 
Z-ADD 
MOVEL 
Z-ADD 
Z-ADD 
MOVE 


2187008 
55050240 
LEFTHALF 
2187008 
52953088 
LEFTHALF 


LEFTHALFA 
LEFTHALFB 
KEYCV 
LEFTHALFA 
LEFTHALFB 
KEYCV 


Calculate the Token Validation value by adding every 4 bytes 
and storing the result in the last 4 bytes. 


Z-ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 
ADD 


Copy token to IPINENC 


MOVE 


0 
KEYTVV1 
KEYTVV2 
KEYTVV3 
KEYTVV4 
KEYTVV5 
KEYTVV6 
KEYTVV7 
KEYTVV8 
KEYTVV9 
KEYTVV10 
KEYTVV11 
KEYTVV12 
KEYTVV13 
KEYTVV14 
KEYTVV15 


KEYTOKEN 


KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 
KEYTVV 


IPINKEY 
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Cx* 

Cx* 

CR KKK KK KEKE KKK KKK KKK EKER KER ERE RRR KER KERR ERE RR ER ERE RR ERE RRR ERREERE 
Cx Build an OPINENC key token 

Cx« 

Cx The control vector for an OPINENC key that 

C* has the key part flag set is (in hex): 

Cx 

Cx 00247700 03480000 00247700 03280000 

Cx 

Cx If each 4 byte hex part is converted to decimal you get: 

Cx* 

Cx 2389760 55050240 2389760 52953088 

Cx« 

CR KKK KKK EK KKK KEK KEK RK KEK KEK ERE KK EKER KERR REKERREKRE RK RR ERE REE ERR ERE 
Cx Build the control vector by placing the decimal numbers in 
Cx the appropriate half of the control vector field. 

CR KKK KK KKK KKK KEKE KR EKER KER EKER K RK ER KERR ERE RR EKER KERR ERE REE ERE 


C Z-ADD 2389760 LEFTHALFA 
C Z-ADD 55050240 LEFTHALFB 
C MOVEL LEFTHALF KEYCV 

C Z-ADD 2389760 LEFTHALFA 
C Z-ADD 52953088 LEFTHALFB 
C MOVE LEFTHALF KEYCV 

Cx 


Cx Calculate the Token Validation value by adding every 4 bytes 
C* and storing the result in the last 4 bytes. 


Cx* 

C Z-ADD 0 KEYTVV 
C ADD KEYTVV1 KEYTVV 
C ADD KEYTVV2 KEYTVV 
C ADD KEYTVV3 KEYTVV 
C ADD KEYTVV4 KEYTVV 
C ADD KEYTVV5 KEYTVV 
C ADD KEYTVV6 KEYTVV 
C ADD KEYTVV7 KEYTVV 
C ADD KEYTVV8 KEYTVV 
C ADD KEYTVV9 KEYTVV 
C ADD KEYTVV10 KEYTVV 
C ADD KEYTVV11 KEYTVV 
C ADD KEYTVV12 KEYTVV 
C ADD KEYTVV13 KEYTVV 
C ADD KEYTVV14 KEYTVV 
C ADD KEYTVV15 KEYTVV 
Cx* 

Cx Copy token to OPINENC 

Cx 

C MOVE KEYTOKEN OPINKEY 
C* 

Cx* 

CR KKK KK KEKE KKK KKK KKK KER KEK ERE KK EKER KERR EKER REE KERR ERE REE ERR ERE 
Cx« 

C* Clear key value for PINGEN/PINVER form will be: 
Cx 

Cx 01234567 01765432 01234567 01765432 

Cx« 


Cx The key will be imported into two parts that get exclusived 
Cx OR'ed together. This program uses as key parts: 


C* 00224466 00775533 00224466 00775533 and 
Cx 01010101 01010101 01010101 01010101 
Cx Converting these to decimal results in 


Cx 2245734 7820595 2245734 7820595 and 
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Cx 16843009 16843009 16843009 16843009 

C* 

Cx In this example, the left half of the key is the same as 

Cx the right half. PIN keys in CCA are double length keys. 

Cx However, some implementation of DES (including Cryptographic 
Cx Support/400) use single length keys for PINs. If both 

Cx halves of a double are the same, then they produce the 

Cx same output as a single length key, thereby allowing you 

Cx to exchange data with non-CCA systems. 

CR KKK KKK KKK KKK KR KR EKER KKK ERK KK EKER KEK KEKE KK EKER KERR ER ERK RK ERR RERE 


Cx Import the PINGEN key 

CR KKKKKEKKKKKK KKK KREKERKEER 

C MOVEL ‘FIRST! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

CK K KA KKK KKK KKK KKK RE RE KK EK ERK KK EKER KKK RK RRR ERE RK RR ERE RK RK ERR ERE 
Cx Build the next clear key part by placing the decimal numbers 
Cx in the appropriate half of the clear key field. 


CR K KK KKK KEK KKK EKER KER ERK ER ERE KK RK ERK RR ERR ER ER ERR RR ERE RE RK ERR ERE 


C Z-ADD 16843009 LEFTHALFA 
C Z-ADD 16843009 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CK KKK KKK KKK KK KEKE KR EK KEK KKK ERK KKK KER KKK RK KKK EKER KERR EKER KERR ERR ERE 


Cx Call Key Part Import the first time for the PINGEN key 


CK KA KKK KKK KK KKK KR ERE KK EK ERK KK EKER KKK RK KKK ERE RK RR ERE RRR ERR ERE 


C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

Cc RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINGENKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CRRA KKK KKK KKK KKK KEKE KK EK ERK KKK KER KKK EK KERR ER ERK RR ER ERE RK ERR ERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CARR KA KKK KKK KKK KR KR KEKE KK KEK ER KKK KK ER KKK EKER KEKE KERR ERE KERR ERR ERE 


C Z-ADD 2245734 LEFTHALFA 
C Z-ADD 7820595 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CK KARR KK KKK KK KKK KR EKER KKK ERK KK EKER KKK EKER EKER KERR ERE RK RK ERR ERE 


Cx Call Key Part Import the second time for the PINGEN key 


CR KKK KK KK KKK KK KKK KR EKER KER ER KERR RK ERK RR EKER KEK ERR RR ERE RK RKRE REE 


C MOVEL "LAST : RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINGENKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK KKK KKK KKK KR EKER KER ERE KK EKER RRR ERR ER EKER KERR ERE RE RKERRERE 


Cx Import the PINVER key * 


CK KKK KK KK KKK KK KKK KR EKERKKEER 


C MOVEL "FIRST RULEARRAY 


LR 


LR 
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C Z-ADD 1 RULEARRAYCNT 
C Z-ADD 16843009 LEFTHALFA 

C Z-ADD 16843009 LEFTHALFB 

C MOVEL LEFTHALF CLEARKEY 

C MOVE LEFTHALF CLEARKEY 


CK KKK KKK EK KKK KKK KR KK ERK KEK ERE KK KK EKER KEKE KR ERE RK RR EKER ERR ERR ERE 


Cx Call Key Part Import the first time for the PINVER key 


CR KKK KK KEK KKK KKK KKK EKER KER ERE KK RK EKER KEK ERR ERE RRR RE KE REE ERR 


C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINVERKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR K KK KKK KKK KKK KEK RK K ERK EKER ERK RK EKER KEK ERR ERE RRR ERE RRR ERREERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CK KKK KKK KKK KK KKK KR KK ERK EK ERE KK EK ERE KR RK KERR ERE RK RR ER ERE RR ERR ERE 


C Z-ADD 2245734 LEFTHALFA 
C Z-ADD 7820595 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK KKK KKK KEK RK KEK KKK ERE KK EK EK KERR EKER EKER KERR ERE REE EKRERE 


Cx Call Key Part Import the second time for the PINVER key 


CR KK KKK KEKE KKK KEKE KR KK ERK ER ERE KK EKER KERR ER ERR ERE RE R ERE REE ERR 


C MOVEL "LAST ' RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C PINVERKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR K KK KARR KKK KK KKK KKK KEK KKK ERE KKK KEKE KR RK KERR ERE RK RR EKER KERR ERR KEKE 
Cx Clear key value for IPINENC/OPINENC key pair will be: 

C* 012332EF 01020408 012332EF 01020408 

Cx* 

Cx The key will be imported into two parts that get exclusived 
Cx OR'ed together. This program uses as key parts: 

Cx« 

Cx 002233EE 00030509 002233EE 00030509 and 

Cx* 

Cx 01010101 01010101 01010101 01010101 

Cx« 

Cx Converting these to decimal results in 

Cx 

C* 2241518 197897 2241518 197897 and 

Cx« 

Cx 16843009 16843009 16843009 16843009 

CR K KKK KEKE KKK KEK KKK EKER KER ER EKER KER KERR EKER ER ERR RERERERKE RR ERR 
Cx Import the PINVER key * 

CR KKK KK KEKKEK KKK REKK KR EKERKEER 

C MOVEL ‘FIRST! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
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LR 


CR K KA KKK KKK KKK KKK RE K EK KEK ERK KK EKER KKK RK KERR ER ERK RR ER ERE RRR RR ERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CR K KKK KEKE KKK KEKE KR EKER KER ERE KK RK ER KERR EKER EKER KERR EKER KERR ERR ERE 


C Z-ADD 16843009 LEFTHALFA 
C Z-ADD 16843009 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK KKK KK KKK KEKE KE KK KEK ERK KKK KER KKK RK KKK ER ERK RR EKER KEKE RRR 


Cx Call Key Part Import the first time for the IPINENC key 


CR KKK KKK KKK KKK KKK KEKE KK EK ERK KK EKER KKK EK KKK EKER KERR ER ERE RK ERR ERE 


C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C IPINKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CR KKK KKK KKK KK KKK KR KEK KEK ER KEK KER ER KKK RK KERR EKER KERR EKER KERR ERR ERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CR K KARR KK KKK KKK KKK RE RE KK EK ERK KKK KER KKK RK KKK EKER KERR ER ERK RK ERR ERE 


C Z-ADD 2241518 LEFTHALFA 
C Z-ADD 197897 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR K KKK KKK KKK KK EKER RE RE KK EK ERK KK EKER KEK KEKE KK EKER KERR ER ERK RK ERR RERE 


Cx Call Key Part Import the second time for the IPINENC key 


CR KKK KK KKK KKK KEKE KR ERE RK ER ERK KK EKER KR KEK REE ERE RRR ERE RR EKERREERE 


C MOVEL "LAST ; RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C CLEARKEY: 

C IPINKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 


CRRA KK KKK KK KK KKK KEKE KERR ER ERE KK EKER KERR ERR ER ER ERE RR ERE RE RRR RRR 


Cx Import the OPINENC key * 

CXR KK KKK KKKKKKKK KR EKEKKER 

C MOVEL "FIRST! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

CR KKK KK KKK KK KK KKK KR EKER KER ERK KK EKER KR KERR ERE KERR RR ERE RE REKRERRERE 
Cx Build the clear key part by placing the decimal number in 

Cx the appropriate half of the clear key field. 


CR KKK KKK KKK KK KKK KR ERE KK EK ERK KKK KER KKK RK KEK KEKE RK RR ERE REE ERR ERE 


C Z-ADD 16843009 LEFTHALFA 
C Z-ADD 16843009 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK KEK KKK KEKE KR EKER KER ERE KK EKER KR KEK EER EKER KERR ERE RE RRR REE 
Cx Call Key Part Import the first time for the OPINENC key 

CK KKK KKK KKK KK EKER KEKE RK EKER KEKE RK ERK RR EK REE EK ERE RR EKER EKRERRERE 
C CALLP CSNBKPI (RETURNCODE: 

C REASONCODE: 
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LR 


LR 
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c EXITDATALEN: 
c EXITDATA: 

c RULEARRAYCNT: 
c RULEARRAY : 

c CLEARKEY: 

c OPINKEY) 

c RETURNCODE —-IFGT 4 

c MOVEL 'CSNBKPI ! FAILMESSAGE 
c EXSR SNDFAILMSG 

c SETON 

c ENDIF 


CR K KK KKK EK KKK RK KKK EKER KER ERE KK RK ERR KR ER ERR ERE RRR EKER KERR ERE RERE 
Cx Build the clear key part by placing the decimal number in 
Cx the appropriate half of the clear key field. 


CR KKK KKK KKK KK KEKE KR KK EK KKK ERR KK EKER KKK EKER KER ERK RR ERE REE EKER E 


C Z-ADD 2241518 LEFTHALFA 
C Z-ADD 197897 LEFTHALFB 
C MOVEL LEFTHALF CLEARKEY 
C MOVE LEFTHALF CLEARKEY 


CR KKK KKK KKK KK KEK KEK RK KEK KEK ERE KK EKER KERR RK KERR EKER KERR EKER KERR ERR ERE 


Cx Call Key Part Import the second time for the OPINENC key 


CR K KAKA KEKE KKK KEK KKK EKER KER ERE KK RK ERR KER EK ERR ERE REE ERE RRR ERR ERE 


C MOVEL "LAST . RULEARRAY 

C CALLP CSNBKPI (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXTTDATA: 

C RULEARRAYCNT : 
C RULEARRAY : 

C CLEARKEY: 

C OPINKEY) 

C RETURNCODE IFGT 4 

C MOVEL "CSNBKPI' FAILMESSAGE 
C EXSR SNDFAILMSG 

C SETON 

C ENDIF 

Cx 


CR KKK KKK KKK KK KEKE KKK KEK KEK ERE KK EKER KEK KEK KERR ERE RK RR ERE KERR ERR ERE 
Cx Generate a Clear PIN with CSNBPGN (Clear_PIN Generate) 

Cx Rule_array_count = 1 

Cx Rule_array = "IBM-PIN" (Same as Crypto Support/400) 

Cx PIN length = 8 

Cx PIN Check length = 8 (But is ignored for IBM-PIN) 

Cx Data array: 

Cx Dec. table set to 0123456789123456 

C* validation dta =  1111222233334444 


Cx clear PIN = ignored 

CR KK A KKK KKK KK KKK KR KK ERK KEK ERE KK KK EK KERR EK ERR ERE RRR RRR ERE RR ERR ERE 
C Z-ADD 1 RULEARRAYCNT 

C MOVEL 'IBM-PIN ! RULEARRAY 

C Z-ADD 8 PINLEN 

C Z-ADD 8 PINCKL 

C MOVEL 'Q1234567' DECTABLE 

C MOVE "89123456! DECTABLE 

C MOVEL '11112222' VALDATA 

C MOVE "33334444 ' VALDATA 


CR KKK KK KEKE KKK KKK KERR KK ERK KEK ERE KKK KERR RRR RR EKER KERR EKER KERR ERR ERE 

Cx Call Clear PIN Generate 

CR KKK KK KEKE KKK KKK KEK KKK ERK ER ERE KK RK EKER KEK ERR ERE RRR ERE RR RR ERREERE 

CALLP CSNBPGN (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
PINGENKEY: 
RULEARRAYCNT: 
RULEARRAY : 
PINLEN: 


RAOAAOaAAAaA©A 
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LR 


LR 


C 
C 
C 
C 
C 
C 
C 
C 
Cx 


Cx« 


RETURNCODE IFGT 
MOVEL 
EXSR 
SETON 
ENDIF 


PINCKL: 


DATAARRAY : 
CPIN) 

4 

'CSNBPGN' FAILMESSAGE 

SNDFAILMSG 


CK KKK KKK KKK KK KKK KR EKER KK KEK ERK KK EKER KERR EK KKK EKER KERR ERE REE ERR ERE 


Encrypt the clear PIN using CSNBCPE (Clear_PIN Encrypt) 


Cx* 
Cx* 
Cx* 
Cx« 
Cx* 
Cx* 


Rule_array_count = 1 


Rule_array = "ENCRYPT " 


PIN Profile = "3624 
PAN data is ignored 


NONE FN 


Sequence number is ignored but set to 99999 anyway 
CR KKK KKK KKK KKK KKK KR EKER KER ERK KK RK ER KERR ERE ER EKER KERR ERE RE RK ERR 


Z-ADD 
MOVEL 
MOVEL 
MOVE 
MOVE 
Z-ADD 


1 RULEARRAYCNT 
"ENCRYPT ' RULEARRAY 
"3624 ; PINFORMAT 
"NONE : FORMATCONTROL 
‘ F PADDIGIT 
99999 SEQNUMBER 


CR KKK KKK KKK KKK KKK RE KE KK EK ER KEK KEK ER KKK RK EK KER ERK RR ERE KKK ERR ERE 


Cx 


Call Clear PIN Encrypt 


CR K KARR KKK KKK KEKE KR EKER KER ERK KK EKER KKK EKER EKER KERR EKER EKER ERE 


C 


AOODOAOAAQ0F00 O00 0 


a 


Cx 
Cx 


CALLP 


RETURNCODE IFGT 
MOVEL 
EXSR 
SETON 
ENDIF 


CSNBCPE (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
OPINKEY: 
RULEARRAYCNT: 
RULEARRAY : 
CPIN: 
PROFILE: 

PAN: 
SEQNUMBER: 
EPIN) 

4 
"CSNBCPE' 
SNDFAILMSG 


FAILMESSAGE 


CRRA KKK KKK KK KKK KR EKER KKK ERK KK EKER KKK RK KKK ER ERK RR ERE KERR ERR ERE 


C* Verify encrypted PIN using CSNBPVR (Encrypted_PIN_ Verify) 


CR K KKK KKK KKK KK KKK KR ERE RK ER ER KEK KEK ER KERR EKER EKER KERR ERE RE RR ERR 


C 


DADADADDAAAMAAAAMAADAANAAANAIANM 


MOVEL 


CALLP 


RETURNCODE IFGT 
MOVEL 
EXSR 


‘IBM-PIN ' RULEARRAY 


CSNBPVR (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
IPINKEY: 
PINVERKEY: 
PROFILE: 

PAN: 

EPIN: 
RULEARRAYCNT : 
RULEARRAY : 
PINCKL: 
DATAARRAY ) 

4 
"CSNBPVR' 
SNDFAILMSG 


FAILMESSAGE 


LR 


LR 
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C SETON LR 
C ENDIF 

Cx* 

III III RR RII ICI RR I III EK 


Cx Send successful completion message 
CR K KKK KKK KKK KK KKK KKK KEK KEK ERE KK EKER KEK RRR ERR EKER KERR EKER ERK ERR ERE 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 

C PARM GOODMESSAGE 

C PARM GOODMSGLENGTH 
C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

Cx 

C SETON LR 
Cx« 


CR K KKK KKK EK KKK KKK KR KK EK KKK ERE KK EKER KEK RRR KERR EKER KERR ERE RE K RRR ERE 


Cx Subroutine to send a failure message 
CR KKK KK KEKE KKK KEK KKK EKER KER ERE RRR KER ERR EK ERR ER ERE RR ERE RRR ERR 


C SNDFAILMSG BEGSR 


C MOVE FAILMESSAGE = FAILMSGTEXT 
C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM FAILMSG 

C PARM FAILMSGLENGTH 
C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


Generate and verify a digital signature 
Generating a digital signature 


You can protect data from undetected changes by including a proof of identity value called a digital 
signature. A digital signature relies on hashing and public key cryptography. When you sign data, you hash 
the data and encrypt the results with your private key. The encrypted hash value is called a digital 
signature. 


If you change the original data, a different digital signature will be generated. 
To use a PKA key to sign a file, write a program or change this program |“Example: Signing a file with your 
4758 Coprocessor” on page 171 


Verifying a digital signature 


Verifying a digital signature is the opposite of signing data. Verifying a signature will tell you if the signed 
data has changed or not. When a digital signature is verified, the signature is decrypted using the public 
key to produce the original hash value. The data that was signed is hashed. If the two hash values match, 


then the signature has been verified. To do this, write a program or change this |“Example: Verifying a 


digital signature with your 4758 Coprocessor” on page 175 
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Note: If you choose to use the program examples provided, change them to suit your specific needs. For 
security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


Example: Signing a file with your 4758 Coprocessor 
Change this program example to suit your needs for signing a file with your 4758 Coprocessor. 


[eesetecasseeseseaseaseseeneseese rsSaeseeeesecesceene see saeeeceee */ 
/* Description: Digitally signs a streams file. x/ 
/* */ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 */ 

/* x/ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function »*/ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 


/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* x/ 
/* Parameters: File to be signed x*/ 
/* File to contain signature x/ 
/* Key label of key to use */ 
/* */ 
/* Examples: x/ 
/* CALL PGM(SIGNFILE) PARM('file_to_sign' 'file_to_hold_sign' */ 
/* 'key_label'); */ 
/* */ 
/* Note: The CCA verbs used in the this program are more fully = */ 
/* described in the IBM 4758 CCA Basic Services Reference */ 
/* and Guide (SC31-8609) publication. x/ 
/* */ 
/* Note: This program assumes the card you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the x/ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x*/ 
/* x/ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(SIGNFILE) SRCFILE(SAMPLE) SYSIFCOPT(*IFSIO) */ 
/* CRTPGM PGM(SIGNFILE) MODULE(SIGNFILE) */ 
/* BNDSRVPGM(QCCA/CSNDDSG QCCA/CSNBOWH) */ 
/* x/ 
/* Note: authority to the CSNDDSG and CSNBOWH service programs  */ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/*  Digital_Signature_Generate (CSNDDSG) */ 
/* One_Way_Hash (CSNBOWH) x/ 
J wees ese Seaccsce sense csueuseessessesseSsses-Sseesensseesasssescs */ 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 

| eee ee eee ee ee */ 

/* standard return codes */ 

[esoneeeseaeeeossaseossoeesicpSse sees ese e eee see */ 


#define ERROR -1 
#define OK 0 
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int hash_file(long h_len, char h_out[128], FILE *t_in); 


int main(int argc, char *argv[]) 


{ 


[kee eee sees aeons oseeeeeeraee scar sae a Ss Soe ae Se ee */ 
/* standard CCA parameters x/ 
[xeeecscesssseonees sens tee estas ae see see seseesnsessesseese */ 


long return_code; 
long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count 
char rule_array[1] [8]; 


iT 
Oo 
i 

we 


iT} 
Oo 
i 

we 


long PKA_private_key_identifier_length = 64; 
char PKA _private_key_identifier[64]; 

long hash_length = 16L; 
char hash[128] ; 

long signature_field_length 
long signature_bit_length = 
char signature_field[256]; 
char key_label [64]; 

long key_token_length = 2500L; 
char key_token[2500] ; 


= 128L; 
OL; 


FILE *file2sign; 
FILE *signature; 
int hash_return; 


if (argc < 2) 


printf("Name of file to be signed is missing."); 
return ERROR; 
} 


else if (argc < 3) 


printf("Name of file where the signature should "); 
printf("be written is missing."); 
return ERROR; 
} 
else if (argc < 4) 
{ 
printf("Key label for the key to be used for signing is missing."); 
return ERROR; 
} 


if ( (strlen(argv[3])) > 64 ) 


{ 
printf("Invalid Key Label. Key label longer than 64."); 
return ERROR; 
} 
else 
{ 
memset (PKA _private_key_identifier, ' ', 64); 
memcpy (PKA_private_key_ identifier, argv[3],strlen(argv[3])); 
} 


/* Open the file that is being signed. */ 
if ( (file2sign = fopen(argv[1],"rb")) == NULL) 
{ 
printf("Opening of file %s failed.",argv[1]); 
return ERROR; 
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} 


/* Obtain a hash value for the file. */ 
hash_return = 


/* Close the file. */ 
fclose(file2sign); 


if (hash_return != OK) 


hash_file(hash_length, hash, file2sign); 


printf("Signature generation failed due to hash error.\n"); 


else 


{ 

/* Use CSNDDSG to generate the signature. */ 
CSNDDSG(&return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

(char *) rule_array, 
&PKA_private_key_identifier_length, 
PKA_private_key_identifier, 
&hash_length, 

hash, 

&signature_field_length, 
&signature_bit_length, 
signature_field); 


} 


if (return_code != 0) 


printf("Signature generation failed with return/reason code %1d/%ld", 


return_code, reason_code); 
return ERROR; 
} 


else 


printf("Signature generation was successful."); 


printf ("Return/Reason codes = %ld/%ld\n", return_code, reason_code); 
printf("Signature has length = %ld\n",signature_field_length) ; 


signature = fopen(argv[2],"wb"); 
if (signature == NULL) 


printf("Open of file %s failed.",argv[2]); 
printf("Signature was not saved."); 
return ERROR; 

} 


fwrite(signature_field, 1, signature_field_length, signature); 


fclose(signature) ; 


printf("Signature was saved successfully in %s.", argv[2]); 


return OK; 
} 
} 


int hash_file(long h_len, char h_out[128], FILE *t_in) 
{ 


long return_code; 
long reason_code; 
long exit_data_length = 0; 
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char exit_data[2]; 
long rule_array_count = 2; 
char rule_array[2] [8]; 


[xSea5 Sees osee eee Saree eee se cee eae see see seseesnasssesseese = 
long text_length; 

char text[1024]; 

long chaining _vector_length = 128; 

char chaining_vector[128] ; 


long file_length; 
fseek(t_in, 0, SEEK_END); 


file_length = ftell(t_in); 
rewind(t_in); 


text_length = fread(text, 1, 1024, t_in); 


memcpy(rule_array[0], "MD5 ", 8); 
if (file_length <= 1024) { 

memcpy(rule_array[1], "ONLY ", 8); 
else { 


memcpy(rule_array[1], "FIRST ", 8); 
} 


while (file_length > 0) 
{ 
CSNBOWH(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
&text_length, 
text, 
&chaining_vector_length, 
chaining_vector, 
&h_len, 
h_out); 


if (return_code != Q) 
break; 


printf("Hash iteration worked.\n"); 
file_length -= text_length; 

if (file_length > 0) 

text_length = fread(text, 1, 1024, t_in); 


if (file_length <= 1024) { 
memcpy(rule_array[1], "LAST We Oye 
} 


else { 
memcpy(rule_array[1], "MIDDLE ", 8); 
} 


} 
} 


if (return_code != Q) 


{ 


printf("Hash function failed with return/reason code %1d/%ld\n", 
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m 


p 
P 


p 
r 


} 


Example: Verifying a digital signature with your 4758 Coprocessor 
Change this program example to suit your needs for verifying a digital signature with your 4758 


return_code, reason_code); 
eturn ERROR; 
} 


else 


rintf("Hash completed successfully.\n"); 


rintf("hash length = %ld\n", h_len); 
rintf("hash = %.32s\n\n", h_out); 
eturn OK; 


} 


Coprocessor. 

[Seen eeeteeeeeseeheee ene esssasessesssesceese esha Scesceeaeaseuns */ 
/* Description: Verifies the digital signature of an IFS file */ 
/* produced by the SIGNFILE sample program. */ 
/* x/ 
/* COPYRIGHT 5769-SS1 (c) IBM Corp 1999 x/ 

/* x/ 
/* This material contains programming source code for your */ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these programs. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* */ 
/* Parameters: Signed file x/ 
/* File containing the signature x/ 
/* Key label of the key to use */ 
/* x/ 
/* Examples: */ 
/* CALL PGM(VERFILESIG) PARM('name_of_signed_file' + */ 
/* ‘name_of_file_w signature’ + x/ 
/* 'key_label'); */ 
/* x/ 
/* Note: The CCA verbs used in the this program are more fully = */ 
/* described in the IBM 4758 CCA Basic Services Reference */ 
/* and Guide (SC31-8609) publication. x/ 
/* x/ 
/* Note: This program assumes the card you want to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or has been explicitly named using the x*/ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* */ 
/* Use the following commands to compile this program: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(VERFILESIG) SRCFILE(SAMPLE) SYSIFCOPT(*IFSIO) «/ 
/* CRTPGM PGM(SIGNFILE) MODULE(SIGNFILE) + */ 
/* BNDSRVPGM(QCCA/CSNDDSV QCCA/CSNBOWH) */ 
/* x/ 
/* Note: authority to the CSNDDSV and CSNBOWH service programs  */ 
/* in the QCCA library is assumed. */ 
/* x/ 
/* Common Cryptographic Architecture (CCA) verbs used: x/ 
/* Digital Signature Verify (CSNDDSV) */ 
/* One_Way_ Hash (CSNBOWH) x/ 
JeosesesseetorssesossseaeesessSsseecssceeesssSaes acess ssesseeeas */ 
#include <stdlib.h> 
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#include <stdio.h> 
#include <string.h> 


#include "csucincl.h" /* header file for CCA Cryptographic 
Service Provider for iSeries */ 

Passe sscussccssoscsseeee secs sesacssboresesassessossosscecese */ 

/* standard return codes x/ 

[#hsesecees setenes eases Seeassascessosese tease ae sees seeeseeaS */ 


#define ERROR -1 
#define OK 0 


int hash_file(long h_len, char h_out[128], FILE *t_in); 


int main(int argc, char *argv[]) 


{ 
[xeSeeee tee ce eee sesce sates sean ae cise see see See ese se tes Sees */ 
/* standard CCA parameters x/ 
jxeeSe et eesess seesesee eters ecce see soe sea seaSseeeeseeaaeesseces */ 


long return_code; 
long reason_code; 
long exit_data_length 
char exit_data[2]; 
long rule_array_count = OL; 
char rule_array[1] [8]; 


iT} 
oO 
i 

we 


| ee a eee */ 
/* parameters unique to this sample program x/ 
| xsaceeesoesesscsesseessessssesscesscesssssaSsesss ose sf Seeeen */ 


long PKA_public_key_identifier_length = 64; 
char PKA_public_key_identifier[64] ; 

long hash_length = 16L; 

char hash[128] ; 

long signature_field_length; 

char signature_field[256] ; 

char key_label [64]; 


FILE *file2verify; 
FILE *signature; 
int hash_return; 


if (argc < 2) 

{ 
printf("Name of file to be verified is missing.\n"); 
return ERROR; 

} 


else if (argc < 3) 


printf("Name of file containing the signature is missing.\n"); 
return ERROR; 
} 


else if (argc < 4) 


printf("Key label for the key to be used for verification is missing.\n"); 
return ERROR; 
} 


if (strlen(argv[3]) > 64 ) 


{ 
printf("Invalid Key Label. Key label longer than 64 bytes."); 
return ERROR; 

} 

else 


{ 
memset (PKA_public_key_identifier, ' ', 64); 
memcpy (PKA_public_key_identifier, argv[3], strlen(argv[3])); 
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} 


/* Open the file that is being verified. */ 
if ( (file2verify = fopen(argv[1],"rb")) == NULL) 


printf("Opening of file %s failed.",argv[1]); 
return ERROR; 
} 


/* Obtain a hash value for the file. */ 
hash_return = hash_file(hash_length, hash, file2verify); 


/* Close the file. */ 
fclose(file2verify); 


if (hash_return != OK) 


printf("Signature verification failed due to hash error.\n"); 
return ERROR; 
} 
else 
{ 
signature = fopen(argv[2],"rb"); 
if (signature == NULL) 


{ 
printf("Open of signature file %s failed.",argv[2]); 
printf("Signature was not verified."); 
return ERROR; 

} 

memset(signature_ field, ' ', 256); 


fseek(signature, 0, SEEK_END); 
signature_field_length = ftell(signature) ; 
rewind(signature) ; 


fread(signature_ field, 1, signature _field_length, signature); 
fclose(signature) ; 


/* Use CSNDDSV to verify the signature. */ 
CSNDDSV (&return_code, 

&reason_code, 

&exit_data_length, 

exit_data, 

&rule_array_count, 

(char *) rule_array, 
&PKA_public_key_identifier_length, 
PKA_public_key_identifier, 
&hash_length, 

hash, 

&signature_field_length, 
signature_field); 


} 


if (return_code != 0) 

{ 
printf("Signature verification failed with return/reason code %1d/%1d", 
return_code, reason_code); 
return ERROR; 

} 


else 


printf("Signature verification was successful."); 
printf ("Return/Reason codes = %ld/%ld\n", return_code, reason code); 
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{ 


int hash_file(long h_len, char h_out[128], FILE *t_in) 
[xeSeseeSssssSosessseneenet seen Heese Sees Sect ees */ 
/* standard CCA parameters x/ 
[ #seceesewescssesensesscesssseessessss ase sSeese ce sse St Seeeee */ 
long return_code; 
long reason_code; 
long exit_data_length = 0; 
char exit_data[2]; 
long rule_array_count = 2; 
char rule_array[2] [8]; 
[Reese eee see sesse See ase secee see noe see seaesesesseeaaeee secs] */ 
/* parameters unique to this function x/ 
[x e@eeeae sa Gs ceeses see seaee see seas sees oes See ea ee */ 
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long text_length; 
char text[1024]; 


long chaining _vector_length = 128; 
char chaining_vector[128] ; 


long file_length; 


fseek(t_in, 0, SEEK_END); 


file_length = 
rewind(t_in); 


text_length = 


memcpy(rule_array[0], "MD5 


if (file_length <= 
memcpy (rule_array[1], 


else { 
memcpy (rule_array[1], 


while (file_length 
{ 
CSNBOWH(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *) rule_array, 
&text_length, 
text, 


ftell(t_in); 


fread(text, 1, 1024, t_in); 


a 8); 
1024) { 
"ONLY ", 8); 
"FIRST ", 8); 
> 0) 


&chaining_vector_length, 


chaining vector, 
&h_len, 
h_out) ; 


if (return_code != 0) 
break; 


printf("Hash iteration worked.\n"); 


file_length -= text_length; 


if (file_length > 0) 
{ 


text_length = fread(text, 1, 1024, t_in); 


iSeries: Cryptographic hardware 


if (file_length <= 1024) { 
memcpy(rule_array[1], "LAST ", 8); 
} 


else { 
memcpy(rule_array[1], "MIDDLE ", 8); 
} 


} 
} 


if (return_code != 0) 


printf("Hash function failed with return/reason code %1d/%ld\n", 
return_code, reason_code); 
return ERROR; 


else 


printf("Hash completed successfully.\n"); 
printf("hash length = %ld\n", h_len); 
printf("hash = %.32s\n\n", h_out); 

return OK; 


] 
} 
Manage multiple 4758 Cryptographic Coprocessors 


You can have up to eight 4758 Coprocessors per system. Spreading the work across multiple 4758 
Coprocessors and multiple jobs gives you better performance provided that they are all configured the 
same. Only one Coprocessor (cryptographic device description) may be allocated to a job at one time. 
However, the job can switch between Coprocessors by deallocating the current Coprocessor and allocating 
a new one. For the OS/400 SSL user, the allocation and deallocation of the Coprocessors is managed by 
the system if the SSL configuration in DCM indicates that more than one Coprocessor is to be used for 
SSL session establishment. 


If you configure all of the Coprocessors the same, then all operational keys will work identically on all of 
the Coprocessors. Any data encrypted on one Coprocessor can be decrypted on a different Coprocessor. 
All key store files will work interchangeably with any of the Coprocessors. The most important part of 
configuring the Coprocessors identically is the master keys. If you entered the master key in parts for one 
Coprocessor, you must enter the same master key parts for all of the other Coprocessors if you want them 
to work interchangeably. If a random master key was generated inside of the Coprocessor, then you must 
clone the master key to the other Coprocessors if you want all of the Coprocessors to work 
interchangeably. 


There may be certain situations where you do not want all of the Coprocessors to be configured the same. 
They could all have different configurations or they could be set up in groups where the configuration 
within a group is the same but between groups is different. For these cases, all operational keys may not 
work identically on all of the Coprocessors. Data encrypted on one Coprocessor may not be able to be 
recovered on a different Coprocessor. Also, the keystore files may not work interchangeably among 
Coprocessors. For these situations, you must keep track of which keystore files and operational keys will 
work for a given Coprocessor. While configuring the Coprocessors differently may limit the scalability of 
cryptographic applications, it can provide more granularity in terms of security. For example, you can grant 
different object authorities to different cryptographic device descriptions. 


If you use retained PKA keys then the Coprocessors are also not interchangeable. Retained keys can not 
be exported in any manner outside of the Coprocessor. Therefore, any cryptographic request that uses 
that retained key, must be sent to the Coprocessor that stores the retained key. 


The following material is only applicable if you are using OS/400 applications: 


Chapter 5. 4758 Cryptographic Coprocessor for iSeries 179 


Allocating a device 


The Cryptographic_Resource_Allocate (CSUACRA) API verb is used to explicitly allocate a cryptographic 
device to your job so that the system can determine how to route all subsequent cryptographic requests. If 
you use any of the CCA API verbs without first explicitly using the Cryptographic_Resource_Allocate 
(CSUACRA) API verb, the system will attempt to allocate the default cryptographic device. The default 
device is the cryptographic device named CRP01. It must be created by either using the Basic 
Configuration wizard or the Create Device Crypto (CRTDEVCRP) CL command. You only need to use 
CSUACRA when you wish to use a device other than the default cryptographic device. A device allocated 
to a job, either explicitly or implicitly, remains allocated until either the job ends or the device is deallocated 
using the Cryptographic_Resource_Deallocate (CSUACRD) API verb. Two example programs are provided 
for your consideration. One of them is written in ILE C, while the other is written in ILE RPG. Both 
programs perform the same function. 


* |“Example: ILE C program for allocating a Coprocessor” 
¢ “Example: ILE RPG program for allocating a Coprocessor” on page 182 


Deallocating a device 


When you have finished using a 4758 Coprocessor, you should deallocate the 4758 Coprocessor by using 
the Cryptographic_Resource_Deallocate (CSUACRD) API verb. A cryptographic device description can not 
be varied off until all jobs using the device have deallocated it. Two example programs are provided for 
your consideration. One of them is written in ILE C, while the other is written in ILE RPG. Both programs 
perform the same function. 


¢ |“Example: ILE C program for deallocating a Coprocessor’” on page 184 
¢ |“Example: ILE RPG program for deallocating a Coprocessor’” on page 186 


Example: ILE C program for allocating a Coprocessor 
Change this program example to suit your needs for allocating a Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


| Redeeseeesceaeceeaeses sacs eae esse esses es a5 a2 ene eee se — ss eee eee */ 
/* Allocate a crypto device to the job. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x*/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CRPALLOC) (CRPO2) x/ 
/* x/ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Resource Allocate (CSUACRA) . x/ 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Use these commands to compile this program on iSeries: 


ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(CRPALLOC) SRCFILE (SAMPLE) 

CRTPGM PGM(CRPALLOC) MODULE(CRPALLOC) 
BNDSRVPGM(QCCA/CSUACRA) 


Note: Authority to the CSUACRA service program in the 
QCCA library is assumed. 


#include <string.h> 
#include <stdio.h> 
#include "csucincl.h" 


#define ERROR -l 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


long return_code = 0; 

long reason_code = 0; 

long exit_data_length = 2; 
char exit_data[4]; 

char rule_array[2] [8]; 
long rule_array_count = 2; 
long resource_name_length; 


fe LShVs hanes eee Kiem eek eee! 


printf("Device parameter must be specified.\n"); 
return (ERROR) ; 


memcpy(rule_array,"DEVICE ",8); 
rule_array_count = 1; 


CSUACRA( &return_code, &reason_code, &exit_data_leng 
(char *)exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(long *) &resource_name_length, 
(char *) argv[1]); /* resource name 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


Ce ee eee ee ee ee ee a ee eee */ 


knee ia eine er eee enc aii eel eee alle le ee ie im «/ 


*/ 


jdt ce Meee ee eee ee cee elece mkiene */ 


th, 


*/ 
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/* Check the return code and display the results x/ 
[Ross ee Ses eee Sen seceensen Sosa neees Shee seeenseeeeo sas eae Se oer ses «/ 
if ( (return_code == OK) | (return_code == WARNING) ) 

{ 


printf("Request was successful\n"); 

return(OK); 

} 
else 

{ 

printf("Request failed with return/reason codes: %d/%d \n", 

return_code, reason_code); 
return(ERROR) ; 
} 
} 


Example: ILE RPG program for allocating a Coprocessor 
Change this program example to suit your needs for allocating a Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKKKK KK ERK KEKE KKK KERR KR RRR KR ERE RRR RRR RRR RRR RK RR RRR RRR 
D* CRPALLOC 

Dx« 

D* Sample program that allocates a crypto device to the job. 
Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 


D* Parameters: 

Dx Device Name 

Dx« 

D* Example: 

D* CALL PGM(CRPALLOC) PARM(CRPO2) 

Dx« 

Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CRPALLOC) SRCFILE(SAMPLE) 

D* CRTPGM PGM(CRPALLOC) MODULE(CRPALLOC) 


D« BNDSRVPGM(QCCA/CSUACRA) 

Dx« 

D* Note: Authority to the CSUACRA service program in the 
Dx QCCA library is assumed. 

Dx 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic Resource Allocate (CSUACRA) 


Dx« 

[Dee ee ee eee 
D*x Declare variables for CCA SAPI calls 

Pkeseeceescess eases eee See cee eee eee sce see SSeS 
Dx *x Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 
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DREASONCODE Ss 9B 0 


Dx ** Exit data length 
DEXITDATALEN S 9B 0 
Dx ** Exit data 
DEXITDATA > 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 
Dx ** Rule array 
DRULEARRAY S 16 

Dx ** Resource name length 
DRESOURCENAMLEN S$ 9B 0 
Dx ** Resource name 
DRESOURCENAME S 10 

Dx« 


DAK RAKK KKK KKK KKK KKK ERK KK ERK KKK KKK KKK KEK KEKE KKK KER KEK RRR KK RRR 


D* Prototype for Cryptographic_Resource Allocate (CSUACRA) 


DA KRAKKKKKK KERR KKK ERK KK ERR K KERR KERR RRR RRR REE RRR RRR KER EERE 


DCSUACRA PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DRSCNAMLEN 9B 0 

DRSCNAM 10 

Dx« 
DxeeeeeSSesseesesoSeaoes Sas aSseeooea sees esoa ese esesSaseaeee SSeS 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
DxeeHseeeeSoceeeeec eee eee eee eee eee eee eee eee eee eee eee eee 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID 5S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' a) 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER 5 9B © INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B © INZ(0) 

Dx« 

CK KAKA KEK KKK KK KKK KR KK EK KEK ER KKK KK ER KKK EKER KEKE RR RR ER ERK REKERRERE 
Cx START OF PROGRAM * 
Cx* * 
CxkHl Stee eceeeee cles eee lee ence ee See eee eee ease ese see eee * 
C *ENTRY PLIST 

C PARM RESOURCENAME 10 
Cx* * 
CXSeeseeeeeseeseses seca ese ee see es esse see eee ses ee eces ees sees * 
Cx Set the keyword in the rule array * 
CxsesaecessessssectsoseeSle cesses see esses ec eseseoseosSscsessse * 
C MOVEL "DEVICE ' RULEARRAY 

¢ Z-ADD 1 RULEARRAYCNT 

Cx* 

(Cketseaso pelea sates soahsSesssses ses -S Sa =S aes eases oseseass * 

Cx Set the resource name length * 

ee ee ee eee ee eer * 

C Z-ADD 10 RESOURCENAMLEN 

Cx* 

(CkeeseSseecce se seaes sso Sessesee esse ase sae SSeS eassea-seose * 
Cx Call Cryptographic Resource Allocate SAPI * 
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Gkscseessesscicescccusecssessosseseosscssasseceocsssecl secu sete * 
C CALLP CSUACRA (RETURNCODE: 

€ REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C RESOURCENAMLEN: 
C RESOURCENAME) 
CkSeeceasoseoleaeeseSsecs * 

Cx Check the return code * 

CkSessseescenssesesoeeeus * 

C RETURNCODE IFGT 4 

Cx« esasansecenscncecesees * 

Cx * Send error message * 

Cx Pets eeeeeeseeecnee ese * 

C MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx* 

C ELSE 

Cx« 

Cx« + asaecnsassnseecaceeess * 

Cx * Send success message * 

Cx Fesseeetessesec sce eee cs * 

C MOVE MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx 

C ENDIF 

Cx« 

C SETON LR 
Cx« 


CR KKK KKK KKK KK KKK KKK KEK KEK ERE KKK KERR KEK KERR ERE RK RR EKER KER ERR ERE 


Cx Subroutine to send a message 
CR KKK KK KEKE KK KKK KKK EKER KEK ERE KK RK ERK EKE RR ERE RRR ERE RRR ERREERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 


CSUACRA failed with return/reason codes 9999/9999' 
The request completed successfully 


Example: ILE C program for deallocating a Coprocessor 
Change this program example to suit your needs for deallocating a Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


Je eecs Sess ses seeseseee tense sseseee Sess sate sesesoeresoeeS le seecee sees «/ 
/* Deallocate a crypto device from a job. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
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/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* */ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* */ 
/* Parameters: */ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(CRPDEALLOC) (CRPO2) x/ 
/* x/ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic Resource Deallocate (CSUACRD). x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: x*/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(CRPALLOC) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(CRPALLOC) MODULE (CRPALLOC) */ 
/* BNDSRVPGM(QCCA/CSUACRD) x/ 
/* x/ 
/* Note: Authority to the CSUACRD service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
| RecmeseeeneasnsssscsanSsqescee acs sosseeceaeeseoseoeaseassseeeseeccae */ 
#include <string.h> 

#include <stdio.h> 

#include "csucincl.h" 

Peecmstesa aenseasScecScas sass cs sasseseneee seescoeaceseesseecesscae */ 
/* standard return codes */ 
J¥weas soesenecsaassssacee Sessaoss ss eesessses Sse Ssscessfoses sesseece ss */ 


#define ERROR 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


return_code 
reason_code = 0; 
exit_data_length = 2; 
exit_data[4]; 
rule_array[2] [8]; 
rule_array_count = 2; 
resource_name_length; 


as SieSeee see See eee ere see see sree Rees sence ree 


printf("Device parameter must be specified.\n"); 
return(ERROR) ; 
} 
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memcpy(rule_array,"DEVICE ",8); 
rule_array_count = 1; 


[xeecsscesacSeosees sense eesesene sone o oes asses «/ 
/* Set the resource name length */ 
| #seceeeesessse sods cesses see esesseessssass oe ee se Se Sse SS eeee see assess «/ 
resource_name_length = strlen(argv[1]); 

[xeeesscessoSsoseoeseneewe tee cae sa eases ese seeensessesseleecassssssas «/ 
/* Call Cryptographic Resource Deallocate SAPI */ 
(eseceetesssesecsensseseeseSscasstesceses sce scesesstesesssesseasssses «/ 


CSUACRD( &return_code, &reason_code, &exit_data_length, 
(char *)exit_data, 
(long *) &rule_array_count, 
(char *) rule_array, 
(long *) &resource_name_length, 


(char *) argv[1]); /* resource name x/ 
| ee ee eee ee ee «/ 
/* Check the return code and display the results x/ 
[ dseedetesesesscesasesosasesseasecsseesasscescesesetSsseacesseasscses «/ 


if ( (return_code == OK) | (return_code == WARNING) ) 
{ 

printf ("Request was successful\n"); 

return (OK); 

} 
else 

{ 

printf("Request failed with return/reason codes: %d/%d \n", 

return_code, reason_code); 
return (ERROR) ; 
} 
} 


Example: ILE RPG program for deallocating a Coprocessor 
Change this program example to suit your needs for deallocating a Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DARK RKKKKK KK KER KK KEK KKK ERK KKK KEK KKK RRR ERK KKK RE RRR ERK RR ER RRR 
D* CRPDEALLOC 

Dx 

D* Sample program that deallocates a crypto device to the job. 
Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 


D* Parameters: 
Dx Device name 
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Dx 
D* Example: 


D* CALL PGM(CRPDEALLOC) PARM(CRP@2) 


Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(CRPDEALLOC) SRCFILE(SAMPLE) 
D* CRTPGM PGM(CRPDEALLOC) MODULE (CRPDEALLOC) 


D« BNDSRVPGM(QCCA/CSUACRD) 

Dx« 

D* Note: Authority to the CSUACRD service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Resource Deallocate (CSUACRD) 


Dx 

Dx« 

Dkeeeeeaeence eee scat e ee see sees S es eeescesesscsesssss 
D* Declare variables for CCA SAPI 
DkerescesossessceaecesceeSscScecsscsssseesessasscsese 
Dx *x Return code 
DRETURNCODE S 

Dx ** Reason code 
DREASONCODE S 

Dx «x Exit data 1 
DEXITDATALEN 5 

Dx «x Exit data 
DEXITDATA S 

Dx ** Rule array 
DRULEARRAYCNT S 

Dx ** Rule array 
DRULEARRAY S 1 
D« ** Resource na 
DRESOURCENAMLEN §S 

D« ** Resource na 
DRESOURCENAME S 1 
Dx« 


9B 0 


9B 0 
ength 
9B 0 


4 
count 
9B 0 


6 

me length 
9B 0 

me 

0 


DA KRK KKK KKK KKK KKK KEK KEK KERR KEKE KKK KER KERR RR KER RRR RRR KEKE REE 


D* Prototype for Cryptographic_Resource Deallocate (CSUACRD) 


DA KRKK KKK KKK KKK KKK ERK KK RRR KKK KKK KKK KEK KERR KKK KER KK RRR KERR EERE 


DCSUACRD 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DRARRAYCT 
DRARRAY 
DRSCNAMLEN 
DRSCNAM 

Dx 


DMSG 
DMSGLENGTH 

D 

DMSGTEXT 
DFAILRETC 
DFAILRSNC 
DMESSAGEID 
DMESSAGEF TLE 
DMSGKEY 
DMSGTY PE 
DSTACKENTRY 
DSTACKCOUNTER 
DERRCODE 
DBYTESIN 


PR 


9B 0 
9B 0 
9B 0 


** Declares for sending messages to the 
** job log using the QMHSNDPM API 


Ss 7 
S 
DS 

1 7 

4l 4 

46 4 
Ss 

Ss 2 
Ss 

Ss 1 

) 1 
S 
DS 


1 


5 DIM(2) CTDATA PERRCD(1) 


9B 0 INZ(75) 

5 

4 

9 

7 INZ(' 

1 INZ(* 

4 INZ(' ') 
0 —_INZ('*INFO 
0 INZ('* 

9B 0 INZ(2) 

4B 0 INZ(0) 


~~ 
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DBYTESOUT 5 8B @ INZ(0) 


Dx 

CR KKK KKK EK KKK KEKE KR EKER KEK ERE KKK ERE RR EK ERR ERE RE RR ERE REE ERREERE 
Cx START OF PROGRAM * 
Cx * 
Cheese ect eee sews se eee eee ee ee eee eee eee eee eee * 
C *ENTRY PLIST 

C PARM RESOURCENAME 

(kee eee eee ce see see ee eee aes eee hee ee eee eee eesueees * 
Cx Set the keyword in the rule array * 
(kee eeeeee esos eee eee eee eee eee eee cee seue es * 
C MOVEL "DEVICE ' RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

Cx 

CksaeSa Sea SSoee Sasa aaa Se aaa ae aa aS eo eae Se Seas ea= * 

Cx Set the resource name length * 
ee eee ee os * 

C Z-ADD 10 RESOURCENAMLEN 

Cx 

CkSaSS eae SS 2eSe Ses Sea ses Sessa eae SSe See Sass —S See == = S==——= Sees * 
Cx Call Cryptographic Resource Deallocate SAPI * 
CkseSssSs-see ese ee see ose esse las eee eS ee ece esse Sense cesess * 
C CALLP CSUACRD (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT : 

C RULEARRAY : 

C RESOURCENAMLEN: 

C RESOURCENAME) 
Ce¥seeseteeceeecce sec seece * 

Cx Check the return code * 

(C¥eaesoseeaSseseseseesee= * 

C RETURNCODE IFGT 4 

Cx eo ake a ico ana i a om ese * 

Cx * Send error message * 

Cx Se ns i Se a i le * 

Cc MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx 

Cx Peaseseeeweh esr eneeeess * 

Cx * Send success message * 

Cx Heee sees see ese sees es * 

C MOVE MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx* 

C ENDIF 

Cx 

C SETON 

Cx 


CR KKK KKK KKK KK EK KE KR EKER KEK ERE KK RK ERE KR EK ERR ER ERE RR ERE REE ERR ERE 


Cx Subroutine to send a message 
CR KKK KKK KKK KK KKK KR KK ERK KEK ERE RK EKER KEK KEK KERR ERE RK RR EKER ERR ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 

C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 

C PARM STACKCOUNTER 

C PARM MSGKEY 
iSeries: Cryptographic hardware 
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PARM ERRCODE 


C 
C ENDSR 


Cx 
** 
CSUACRD failed with return/reason codes 9999/9999' 
The request completed successfully 


Clone master keys 


Master key cloning is a method for securely copying a master key from one 4758 Coprocessor to another 
without exposing the value of the master key. This is performed by a process of splitting the master key 
into n shares, where nis a number from 1 to 15. m shares are required to rebuild the master key in 
another Coprocessor, where mis a number from 1 to 15 and less than or equal to n. 


The term “cloning” is used to differentiate the process from "copying” because no one share, or any 
combination of fewer than m shares, provide sufficient information needed to rebuild the master key. 


The Coprocessor containing the master key to be cloned is referred to as either the master-key-share 
source node or the Sender. The Sender must generate a retained RSA key pair. This private key must 
also have been marked as suitable for use with cloning when it was generated. The key is known as either 
the Coprocessor Share Signing key or the Sender key. The Coprocessor that will receive the master key is 
referred to as either the master-key-share target node or the Receiver. The Receiver must also generate a 
retained RSA key pair and must also have been marked as suitable for use with cloning. This key is 
known as either the Coprocessor Share Receiving key or simply the Receiver key. 


Both the Sender and Receiver public keys must be digitally signed or certified by a retained private key in 
a Coprocessor, referred to as the public key certifying node or the Certifier. This retained private key is the 
Certifier key. It is also referred to as the Share Administration key. The associated public key must be 
registered in both the Sender and the Receiver before shares can be generated and received. A 4758 
Coprocessor can take on the role of Certifier only, or can it be both Certifier and Sender, or it can be both 
Certifier and Receiver. 


As each share is generated it is signed by the Coprocessor using the Sender private key and encrypted by 
a newly generated triple DES key. The triple DES key is then wrapped or encrypted by the Receiver public 
key. 


As each share is received, the signature on the share is verified using the Sender public key, the triple 
DES key is unwrapped or decrypted using the Receiver private key, and the share decrypted using the 
triple DES key. When m number of shares have been received, the cloned master key will be complete 
within the new master key register of the Receiver. 


The easiest and fastest way to clone master keys is to use the 4758 Cryptographic Coprocessor 
configuration web-based utility. The utility includes Master key cloning advisor. To start the master key 
cloning advisor, follow these steps: 


1. Click on Manage configuration on the 4758 Cryptographic Coprocessor configuration page. 
Click on Master keys. 

Select a device. 

Enter a valid Coprocessor profile and password. 

Click on the Clone button. 


arf on 


If you would prefer to write your own application to clone master keys, you can do so by using the 
following API verbs: 


* Cryptographic_Facility_Control (CSUACFC) 


¢ PKA_Key_Token_Build (CSNDPKB) (may not be needed depending upon how you write your 
application) 
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e PKA_Key_Generate (CSNDPKG) 

* PKA_Public_Key_Register (CSNDPKR) 
* One_Way_Hash (CSNBOWh) 

* Digital_Signature_Generate (CSNDDSG) 
¢ Master_Key_Distribution (CSUAMKD) 


Nine pairs of example programs are provided for your consideration. Each pair contains a program written 
in ILE C and a program written in ILE RPG. Both perform the same function. 


“Example: ILE C program for setting the min and max values for master key shares in your 475 


Coprocessor” 


“Example: ILE RPG program for setting the min and max values for master key shares in your 4758 
Coprocessor” on page 192 


“Example: ILE C program for generating a retained key pair for cloning master keys” on page 19 
“Example: ILE RPG program for generating a retained key pair for cloning master keys” on page 20 
“Example: ILE C program for registering a public key hash” on page 207 

h” on page 21 
¢ |“Example: ILE C program for registering a public key certificate” on page 216 
* |“Example: ILE RPG program for registering a public key certificate” on page 219 
‘ 3 
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“Example: ILE C program for installing a master key share” on page 24 
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The remaining two pairs of example programs are not necessary for master key cloning. They may be 
useful, however, for developing and testing the previous example programs. 


* |“Example: ILE C program for listing retained keys” on page 256 
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” 1 
¢ |“Example: ILE RPG program for deleting retained keys” on page 263 


For more information on cloning master keys, refer to the|IBM 4758 PCI Cryptographic Coprocessor CCA\ 
Basic Services Reference and Guide.” 


Example: ILE C program for setting the min and max values for master key shares 
in your 4758 Coprocessor 

Change this program example to suit your needs for setting the min and max values for master key shares 
in your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
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[xeseeseaseces aoe eeesseseeer asses seas a ae eset se sees seee sense ssece */ 
/* Set the M-of-N values in the 4758 Coprocessor. These values are */ 
/* used in cloning of the master key. The master key is */ 
/* cryptographically split into N number of parts and M number of x*/ 
/* parts are needed to recover it. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 2000 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
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/* guarantee or imply reliability, serviceability, or function */ 


/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide */ 
/* (SC31-8609) publication. */ 
/* */ 
/* Parameters: */ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(SETMOFN) PARM(5 15) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use */ 
/* already identified either by defaulting to the CRPO1 x/ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* */ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(SETMOFN) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(SETMOFN) MODULE (SETMOFN) x/ 
/* BNDSRVPGM(QCCA/CSUACFC) x/ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facilites Control (CSUACFC). x/ 
/* x/ 
eases seecen ses saestoscuecuensesscssasessesseosssseessfosesses-Sese aS */ 
#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries */ 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
#include "decimal .h" 
[kee ceseseseesassasecesee soe see seese eee oseetesessesee sae scsensesseaS */ 
/* standard return codes */ 
[eee ceseeeaeee ee eeeee See cate teee see ese eeaSeee eee tee pee ce seeskeeees */ 


#define ERROR -1 
#define OK 0 
#define WARNING 4 


int main(int argc, char *argv[]) 


{ 


return_code = 0; 
reason_code = 0; 
exit_data_length = 2; 
exit_data[4]; 
rule_array[2] [8]; 
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[#eeasesesese se cseseeeseosssessecseeseeseeeenese te seaSeeesceseeese ses «/ 
/* fields unique to this sample program */ 
[eee hea Sess ee Ssee ses sede asa csa esses sas sano Ses aee Se se = sae eaeeees «/ 


decimal(15,5) mparm, nparm; 
long verb_data[2]; 
long verb_data_length = 8; 


[keen eeerse cee Seeder sseace seam aae sees aes see se se easensesesaseesaasess «/ 
/* Process parameters. Numeric parms from the command line are x/ 
/* passed in decimal 15,5 format. The parms need to be converted x/ 
/* to int format. */ 
[eBeoewessetesscsessesseasasseesseessssss Sessa sssssesfeaceaseassoses «/ 


memcpy (&mparm, argv[1] ,sizeof(mparm) ) ; 
memcpy (&nparm, argv[2] ,sizeof(nparm) ) ; 
verb_data[0] = mparm; 
verb_data[1] = nparm; 


[seer erereacs seoeee seeeceoesearsaesaes—]> =o See Se a= = ae eaaseee «/ 
/* Set keywords in the rule array */ 
| eee «/ 


Jee Soete toe ceeesceseeae ease Sedan ae ese e se seeeeee cee eeee lee eS steeeee «/ 
/* Invoke the verb to set the M of N values */ 
[Reeeeeeaeseeeseneesersseseeseaaae sao oan sees eee oe eee a =e ese a aeeae «/ 


CSUACFC( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 

(char *)rule_array, 
&verb_data_length, 
(unsigned char *)verb data); 


[Reem saw eseceasoaneseeeceressecs- esas ao 5-= Sees eeaee ees a sea oeeensese «/ 
/* Check the results of the call x/ 
[xSeeesSseessesessaesescesaso—qe [e464 bS See see ee se eeeeee «/ 
if ( (return_code == OK) | (return_code == WARNING) ) 

{ 


printf("M of N values were successfully set with "); 

printf("return/reason codes %1d/%ld\n\n", 
return_code, reason_code); 

return(OK) ; 

} 

else 

{ 

printf("An error occurred while setting the M of N values.\n"); 

printf("Return/reason codes %1d/%ld\n\n", 
return_code, reason_code); 

return (ERROR) ; 

} 

} 


Example: ILE RPG program for setting the min and max values for master key 
shares in your 4758 Coprocessor 

Change this program example to suit your needs for setting the min and max values for master key shares 
in your 4758 Coprocessor. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRRKKKKK KKK ERK KKK KKK KE RK KKK RK KKK RRR KEK KKK KER KK RRR KERR ERR KER KE 
D* SETMOFN 

Dx« 

Dx Set the M-of-N values in the 4758 Coprocessor. These values 
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D* are used in cloning of the master key. The master key is 

D* cryptographically split into N number of parts and M number of 
D* parts are needed to recover it. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 

D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

Dx ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx« 

D* Parameters: M and N 

Dx« 

D* Example: 

D* CALL PGM(SETMOFN) PARM(5 10) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(SETMOFN) SRCFILE(SAMPLE) 
D* CRTPGM PGM(SETMOFN) MODULE (SETMOFN) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 
Dx« 


DA KRAKKKKKKK KKK KKK KEK KKK KERR KKK KKK KKK KK RRR KK KR ERK KR ERK KR RRR RRR 


DeeeeceecssesecsecosecoeocsScseeseereseuecsscss 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Verb data length 
DVERBDATALEN 5 9B 0 

Dx ** Verb data contain M (minimum) and N (maximum) 
DVERBDATA DS 8 

DM 9B 0 

DN 9B 0 

Dx« 


DA KRKKKKKK KK KKK KKK ERK KK RRR KKK KK KK KR KEK KKK KKK KER KK RRR KKK ERR ER 


D* Prototype for Cryptographic_Facilty_Control (CSUACFC) 


DA KRKKKKKKK KKK KKK KEK KEK KERR KERR KEKE KERR KER ER KEK RR ER RR RR KEKE REE 


DCSUACFC PR 
DRETCODE 9B 0 
DRSNCODE 9B 0 
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DEXTDTALEN 9B 0 


DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 8 

Dx« 

Dxeeset seese se ece seem se estes ee eee tees eee ee see tee eee eeeseee 
Dx xx Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

DkSeer esses ssscceoee sc esc coos sSoeeseeoSee cece oosScestSeceseses 
DMSG S 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* :) 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx 

CR KKK KKK KKK KK KKK KR KK EK KEK ERE KK EKER KKK EKER EKER RR ERE KERR ERR ERE 
Cx START OF PROGRAM * 
CkSeeSaSSe seca seseae SaaS se aea Sea esa as a5 Seo Sea aa a= SSS * 
C *ENTRY PLIST 

C PARM MVALUE 15 5 
€ PARM NVALUE 15 5 
ee ee ee ee * 
Cx Set the keyword in the rule array * 
Chace eesnes see seeee eh dene ee ace tae theese ese e ee eee eeetee ese see * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "SET-MOFN' RULEARRAY 

C Z-ADD 2 RULEARRAYCNT 

Oks See ese ea se etee ess Se eee eee eee eee eee eee eee eee e ees Ss * 
Cx Set the verb data length to 8 * 
Ckxsceescsecescescooe seca scssesseseoss oss ecscceceosiscescsscseese * 
C Z-ADD 8 VERBDATALEN 
CkeSeesosseeseesccsecseasesseasescese est oScecescescsosesceece] * 
Cx Set the M and N value (Convert from decimal 15 5 to binary)* 
CXsceesceeleeeseesee Seca ses tee ese cee eee eee eee ee ees eceS * 
C EVAL M = MVALUE 

C EVAL N = NVALUE 


CARR KA KK KEKE KKK KEKE KK EKER KER ERE KKK EKER KEK ERR ER ERE RR ERE RR RR ERR ERE 


Cx Call Cryptographic Facilty Control SAPI 


CR KKK KK KEKE KKK KKK KKK EKER KEK ERE KKK KERR RR EK ERR ERE RRR EKER ER ERR 


C CALLP CSUACFC (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

Cc RULEARRAYCNT : 
C RULEARRAY : 

C VERBDATALEN: 
C VERBDATA) 
Ckaeseeesessesseesenwcsus * 

Cx Check the return code * 

Gkscseesecssecoscose sees * 

C RETURNCODE IFGT 0 

Cx Fesseeeseesesse see ee ses * 

Cx * Send error message * 

Cx kKoaSseoseSeeSsssseeeees * 

C MOVEL MSG(1) MSGTEXT 
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** 


cS 
Th 


C MOVE RETURNCODE FAILRETC 
C MOVE REASONCODE FAILRSNC 
C EXSR SNDMSG 

Cx* 

C ELSE 

Cx« KRKKKKKKKKKEKKKEKKKKKKKEKEKE 

Cx * Send success message * 

Cx* KREKKEKKKEKKKEKKEKRKEKKEKEKEKKEEKEER 

C MOVEL MSG (2) MSGTEXT 
C EXSR SNDMSG 

Cx« 

C ENDIF 

Cx* 

C SETON 

Cx« 


CR KKK KKK KKK KK KKK KR EKER KER EKER KEK ERK RR ERE ER EKER KERR ERE RR RR ERR 
Cx Subroutine to send a message 
CR KKK KKK KEK KKK KKK KR EKER KER ERK KK EKER RRR EKER EKER KERR ERE RK RKERRERE 


C SNDMSG BEGSR 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


UACFC failed with return/reason codes 9999/9999. 
e request completed successfully. 


LR 


Example: ILE C program for generating a retained key pair for cloning master keys 


Change this program example to suit your needs for generating a retained key pair for cloning master 


keys. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


[x 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


GENRETAIN 


Sample program to generate a retained key to be used for 
master key cloning. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these program. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 

these programs and files. 

Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 

Parameters: RETAINED KEY _NAME 

Example: 

CALL PGM(GENRETAIN) PARM(TESTKEY) 
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/* */ 


/* x/ 
/* Note: This program assumes the card with the profile is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized x/ 
/* to use this device description. x/ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verbs used are */ 
/* PKA Key Token Build (CSNDPKB) and PKA _Key Generate (CSNDPKG). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(GENRETAIN) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(GENRETAIN) MODULE(GENRETAIN) */ 
/* BNDDIR(QCCA/QC6BNDDIR) */ 
/* x/ 
/* Note: Authority to the CSNDPKG and CSNDPKB service programs x/ 
/* in the QCCA library is assumed. */ 
/* x/ 
| a ee a ne eee et */ 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 


int main(int argc, char *argv[]) 


Jee eteeSeeaseass seassseeess assesses sesss ss sss see Sense sseeSoeeeseeasS «/ 
/* Declares for CCA parameters x*/ 
[Xesesseksesesseseseeee eee Hee ee tees Se Sees see e ose ce eet */ 


long return_code = Q; 
long reason_code = Q; 
long exit_data_length = 0; 
char exit_data[4]; 
char rule_array[24]; 
long rule_array_count; 
long token_len = 2500; 
char token[2500]; 
char regen _data[4]; 
char transport_key_id[4]; 
struct { 
short modlen; 
short modlenfld; 
short pubexplen; 
short prvexplen; 
long pubexp; 
} key_struct; /* Key structure for PKA Key Token Build */ 
long key_struct_length; 
long zero = 0; 


[#eec eee seese ashe sseeseeee ees ete nee See See eeeese eee coe coset «/ 
/* Declares for working with a PKA token */ 
[Reeraedes= ee s=eanssaee aoe e ee eraa ese ess os ea see seeseee 2 —-- seo eae */ 
long pub_sec_len; /* Public section length x/ 
long prv_sec_len; /* Private section length x/ 
long cert_sec_len; /* Certificate section length */ 
long info_subsec_len; /* Information subsection length x/ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
long tempLength; /* Length variable x/ 
long tempLenl, tempLen2; /* temporary length variables x/ 


char pub_token[2500] ; 
long pub_token_len; 
long name_len; 

char name[64]; 
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int i; /* Loop counter 
FILE *fp; /* File pointer 


if (argc < 2) 
{ 


} 


printf("Need to enter a private key name\n"); 
return 1; 


memset (token,0,2500) ; /* Initialize token to 0 


memcpy ((void*)rule_array,"RSA-PRIVKEY-MGMT",16); /* Set rule array 


rule_array_count = 2; 


memset(name,' ', 64); /* Copy key name parameter 
memcpy(name, argv[1], strlen(argv[1])); 
name_len = 64; 


memset ((void*)&key_struct, 0, sizeof(key_struct)); 


key_struct.modlen = 1024; 


/* Modulus length is 1024 


key_struct.pubexplen = 3; 

key_struct.pubexp = 0x01000100; /* Public exponent is 65537 
key_struct_length = sizeof(key struct); 

[RR KRK KEIR KEK AKER A KERIKERI KEKE KER EKERERER | 

/* Call PKA_Key_Token_Build SAPI */ 


[RRR RK ER KK ERK KEK AKER AKER KEKE KER KEREK ER | 


CSNDPKB( &return_code, &reason_code, &exit_data_length, 


exit_data, 
&rule_array_count, 
rule_array, 
&key_struct_length, 
(unsigned char *)&key struct, 
&name_len, 

name, 

&zero, /* 1 */ 
NULL, 

&zero, /* 2 */ 
NULL, 

&zero, /* 3 */ 
NULL, 

&zero, /* 4 / 
NULL, 

&zero, /* 5 */ 
NULL, 

&token_len, 

token); 


if (return_code != Q) 


printf("PKA Key Token Build Failed : return code %d : reason code %d\n", 


return_code, reason_code) ; 
return 1; 


} 


[BERR KKK IKK A KEIR KKK KEK KKK AK KKK IKEA KKK IKKE IKKE IKKE AKER KKK | 


/* Build certificate 


[BERR KER KKK AK ERIK KAR KEK KK EIR KERIKERI KEI AKA KKK A KIER AKER KKK | 


/* Check the number of parameters passed 


*/ 
*/ 


*/ 
*/ 


*/ 


*/ 


/* Determine length of token from length */ 


/* bytes at offset 2 and 3. 
token_len = ((256 * token[2]) + token[3]); 
/* Determine length of private key 
/* section from length bytes at offset 
/* 10. 
prv_sec_len = ((256 * token[10]) + token[11]); 
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pub_sec_len 


/* Determine length of public key section*/ 
/* section from length bytes at offset */ 
/* 10 + private section length x/ 


((256 * token[prv_sec_len + 10]) + 


token[prv_sec_len+ 11]); 
/* Calculate the signature section length*/ 
cert_sec_len = 328 + /* from the signature subsection length, */ 
20 + /* EID subsection length, */ 
12 + /* Serial number subsection length, */ 
4 + /* Information subsection header length, */ 
pub_sec_len + /* Public key subsection length,  */ 
4; /* and the certificate section hdr length*/ 
offset = token_len; /* Offset for additions to token */ 
/* Fill in certicate section header */ 
tempLenl = cert_sec_len; 
tempLenl >>= 8; 
token[offsett+] = 0x40; 
token[offset++] = 0x00; 
token[offset++] = tempLenl; 
token[offset++] = cert_sec_len; 
/* Fill in public key subsection */ 
token[offset++] = 0x41; 
for (i = 1; i < pub_sec_len ; i ++) 
{ 
/* Copy public key to certificate */ 
token[offset++] = token[prv_sec_len +(i+8)]; 
} 
/* Fill Optional Information Subsection Header */ 
info_subsec_len = 20 + /* Length of EID section x/ 
12 + /* Length of serial number section x/ 
4; /* Length of Info subsection header */ 
tempLenl = info_subsec_len; 
tempLenl >>= 8; 
token[offsett+] = 0x42; 
token[offset++] = 0x00; 
token[offset++] = tempLenl; 
token[offset++] = info _subsec_len; 
/* Fill in Public Key Certficate EID subsection */ 
token[offset++] = 0x51; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x14; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offsett+] = 0x00; 
token[offsett+] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 


/* Public key Certificate Serial Number TLV */ 
token[offsett+] = 0x52; 
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token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x0c; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 
token[offset++] = 0x00; 


token[offset++] = 0x00; 
token[offset++] = 0x00; 


/* Fill in Signature Subsection */ 
token[offsett++] = 0x45; 


token[offset++] = 0x00; 
token[offset++] = 0x01; 
token[offset++] = 0x48; 
token[offset++] = 0x01; 
token[offset++] = 0x01; 


for (i = 0 ; i < 64 ;it++) 
{ 
/* Copy private key name out of private key name section */ 
/* into certificate ey 
token[offsett+] = 
token[prv_sec_len + pub_sec_len + 12 + i]; 
} 


token_len = offset + 258; /* add 258 to allow for digtal sig. */ 
token[3] = token_len; /* Set new token length */ 
token[2] = token_len >> 8; 


[RRR KKK KKK AKER A KKK KK IKK KA KKK KK KKK AK KKK KEK IKKE KKK A KKK K KER AKER | 
/* Generate Retained key using PKA token with certificate */ 
[KEK RK ERR RRR AK ERIK KAR KKK K EA KKK KKK IKEA KKK A KKK K KEIR KER AK EEK | 
memcpy((void*)rule_array,"RETAIN CLONE ",16); 

rule_array_count = 2; 

memset (pub_token,0,2500) ; 

pub_token_len = 2500; 

memset (transport_key_id,0,4); 


[KEK RK KER KEKE KKK RAK KER AKER EKER AKER KERK KEE | 
/* Call PKA_Key Generate SAPI */ 
[RE KR KKK KK EA KKK KER AKER EKER K KERR KEKERERER | 
CSNDPKG( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
rule_array, 
&zero, /* regenerated data length */ 
regen_data, 
&token_len, 
token, 
transport_key_id, 
&pub_token_len, 
pub_token) ; 


if (return_code != 0) 


printf("PKA Key Generate Failed : return code %d :reason code %d\n", 
return_code, reason_code); 
return 1; 


} 


[BRK RK EK RK ERIK ERIK RAK KAKA KKK KKK KKK IKEA KKK KK AKER AKER AKER | 


/* Write public key token out to file */ 


[BERR KER KKK AKER A KKK KKK AK KEIR KKK KKK KKK KKK A KKK KK AK KEK AKER AKER | 
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/* Append ".PUB" to key name */ 
memcpy ( (void*) &mame[strlen(argv[1])],".PUB",5); 
fp = fopen(name,"wb"); /* Open the file x/ 


if (!fp) 
printf("File open failed\n"); 
} 

else 


fwrite(pub_token,pub_token_len,1,fp); /* Write token to file */ 


fclose(fp); /* Close the file */ 
printf("Public token written to file %s.\n",name) ; 


} 


name[strlen(argv[1])] = 0; /* Convert name to string */ 
printf("Private key %s is retained in the hardware\n",name) ; 
return 0; 


} 


Example: ILE RPG program for generating a retained key pair for cloning master 
keys 

Change this program example to suit your needs for generating a retained key pair for cloning master 
keys. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DARK RK KARR KK KER KK KEK KKK RRR KKK KEK KKK RRR KEKE KK KER RK RRR KERR EER EKER 
D* GENRETAIN 

Dx« 

D* Sample program to generate a retained key to be used for 

D* master key cloning. 

Dx 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx 

D* Parameters: RETAINED _KEY_NAME 

Dx 

D* Example: 

D* CALL PGM(GENRETAIN) PARM(TESTKEY) 

Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(GENRETAIN) SRCFILE(SAMPLE) 
D* CRTPGM PGM(GENRETAIN) MODULE (GENRETAIN) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

Dx Note: Authority to the CSNDPKG and CSNDPKB service programs 
Dx in the QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
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D* PKA Key Token Build (CSNDPKB) and PKA_Key Generate (CSNDPKG). 


Dx 

DA KRAKKKKK KK KEK KKK ERK KK ERK KERR KERR KERR RRR RRR RRR RRR RRR REE ERR RRRRER 
De en te ee ee 
D* Declare variables used by CCA SAPI calls 
PeeesceoossesecsecssoceeseseSsse lessee se ssceecsSSsssesses= 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx xx Exit data length 

DEXTTDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Token length 

DTOKENLEN 5S 9B 0 INZ(2500) 

Dx ** Token and array for subscripting 
DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx *x Regeneration data 

DREGENDATA S 4 INZ(X'00000000' ) 

Dx ** Transport key encrypting key 
DTRANSPORTKEK S 4 INZ(X'00000000') 

Dx ** Generated keyid 

DGENKEY S 2500 

Dx ** Generated keyid length 

DGENKEYLEN S 9B 0 INZ(2500) 

Dx ** Key name and length 

DKEYNAME S 64 

DKEYNAMEL S 9B 0 INZ(64) 

Dx ** Key structure for PKA Key Token Build 
DKEYSTRUCT DS 

DMODLEN 1 2B 0 

DMODLENFLD 3 4B 0 

DPUBEXPLEN 5 6B 0 

DPRVEXPLEN 7 8B 0 

DPUBEXP 9 12B 0 

D* ** Null parms needed for CSNDPKB and CSNDPKG 
DZERO Ss 9B 0 INZ(O) 

DNULLPTR S * — INZ(*NULL) 

D* ** Key structure length 

DKEYSTRUCTLEN S 9B 0 INZ(12) 

Dx xx Data structure for aligning 2 bytes into 
Dx ** a2 bytes integer 

DLENSTRUCT DS 2 

DMSB 1 1 

DLSB 2 2 

DLENGTH 1 2B 0 

Dx *x Private key section length 
DPRVSECLEN S 9B 0 

Dx ** Public key section length 

DPUBSECLEN S 9B 0 

Dx ** Index into Token array 

DINDEX S 9B 0 

Dx ** Declares for copying private key name 
DNAMEPTR1 S * 

DNAME1 S 64 BASED (NAMEPTR1) 
DNAMEPTR2 S * 

DNAME2 S 64 BASED (NAMEPTR2) 

Dx ** Loop counter 

DI S 9B 0 

D* ** File descriptor 

DFILED S 9B 0 
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D* ** File path and length 

DPATH S 80 INZ(*ALLX'00') 

DPATHLEN S 9B 0 

Dx ** Open flag - Create on open, open for writing, 
Dx a and clear if exists 

DOFLAG Ss 101 @ INZ(X'4A') 

Dx« 


DA KRRKKKKKKK KERR KKK KKK KERR KERR RRR KERR RRR RRR RR ERR RR ERK KR EERE 


D* Prototype for PKA_Key_ Token Build (CSNDPKB) 


DARK RKKKKK KK KER KKK KKK KK ERK KKK KEK KKK RRR ERR KK KR ER KEK RRR KKK ERERE 


DCSNDPKB PR 

DRETCODE 9B 0 
DRSNCODE 9B 0 
DEXTDTALEN 9B 0 
DEXTDTA 4 
DRARRAYCT 9B 0 
DRARRAY 16 
DKEYSTRLEN 9B 0 
DKEYSTR 10 

DKEYNML 9B 0 
DKEYNM 64 

DRSRVLN1 9B 0 
DRSRV1 * VALUE 
DRSRVLN2 9B 0 
DRSRV2 * VALUE 
DRSRVLN3 9B 0 
DRSRV3 * VALUE 
DRSRVLN4 9B 0 
DRSRV4 * VALUE 
DRSRVLN5 9B 0 
DRSRV5 * VALUE 
DTKNLEN 9B 0 

DTKN 2500 OPTIONS (*VARSIZE) 
Dx 


DA KRRKKKKKK KK ERK KEKE KKK KERR KERR RRR KERR RRR RRR KR ER KEKE KKK EERE 


D* Prototype for PKA_Key Generate (CSNDPKG) 


DA RRK KKK KKK KEKE KKK KKK KERR KER RRR KERR RRR KERR ER KEK RRR KERR RRR 


DCSNDPKG PR 

DRETCOD 9B 
DRSNCOD 9B 
DEXTDTALN 9B 
DEXTDT 4 
DRARRYCT 9B 
DRARRY 16 
DREGDTAL 9B 
DREGDTA 20 
DSKTKNL 9B 
DSKTKN 2500 
DTRNKEK 64 
DGENKEYL 9B 
DGENKEY 2500 
Dx 


) 
) 
) 
) 


0 

OPTIONS (*VARSIZE) 
0 

OPTIONS (*VARSIZE) 

OPTIONS (*VARSIZE) 
0 

OPTIONS (*VARSIZE) 


DAKAR KKKKK KKK ERK KK KEK KKK ERK KKK ERK KK RRR KERR KKK REE KEK RRR KK RRR KK 


D* Prototype for open() 


DA RRKKKKKKKK KERR KKK KKK KERR KERR RR KKK RE RRER RRR RR ERR ER KEKE RRR 


Dx value returned = file descriptor (OK), -1 (error) 
Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B @ VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U @ VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DA KRRK KARR KK KEK KKK KKK KK RRR KK RR KKK KERR KR ERK RRR KKK KERR RRR RRR KER KER RERKERKR RK 
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D* Prototype for write() 


DA KRKKKKKKK KKK KKK KEK KKK ERK KERR KERR KERR RR E RRR RR ER KR RR EKER ERR 
Dx value returned = number of bytes actually written, or -1 


Dwrite PR 9B 0 EXTPROC('write') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

D« Data to be written 

D 1200 OPTIONS (*VARSIZE) 
Dx Length of data to write 

D 9B 0 VALUE 

Dx« 


DA KRKKKKKKK KERR KKK ERK KK R KEKE R RRR RRR RK KERR KE RRR RK KERR RRR RR KR ERR RR ERKERRER 


D* Prototype for close() 


DA RKK KK KKK KK KKK KKK ERK KKK KEK KKK KKK KER KK RE RK RRR KR KK RRR RRR RK KR ERR KR ERR KRERK 
D« value returned = @ (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

D* File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

Dees eeooSa Ses ae SoS ee Seas a a Se ie Sa = ee ae = Se =e Se 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 
PxeeSeaSeeSeseSesasoSsaaaa Sasa aSea ose s seas Soe a eae ass a= se = Sasa 
DMSG S 75 DIM(4) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(75) 

D DS 

DMSGTEXT 1 75 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' H) 

DMSGTYPE S 10 INZ('*INFO 1) 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B © INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 

CK KKK KK KKK KK KK KKK KR EKER KER ERE KK RK ERK RR ERE ER EKER ERR ERE RK ERE REE 
Cx START OF PROGRAM * 
Cx« * 
C *ENTRY PLIST 

C PARM KEYNAMEPARM 50 
Cx« a ta a a af * 

Cx * Initialize tokens to 0 * 

Cx tlaeesassescuasaceeeeces= * 

¢ MOVEL *ALLX'00' TOKEN 

C MOVEL *ALLX'00' GENKEY 

Cx* ea a ca wl ac * 

Cx  »* Initialize key struct * 

Cx« tlavcescescoeeensseeeees= * 

¢ Z-ADD 1024 MODLEN 

C Z-ADD 0 MODLENFLD 

C Z-ADD 3 PUBEXPLEN 

C Z-ADD 0 PRVEXPLEN 

C EVAL PUBEXP = 65537 * 256 

Cx* So a a * 

Cx * Copy key name from parm* 

Cx« Kosa saeeeseaeseacsess=ass * 

C MOVEL KEYNAMEPARM KEYNAME 

Cx« Ce ee eee eo * 

Cx * Set the keywords in the rule array * 

Cx* occ S ccc aKa at ea ame eae * 

C MOVEL "RSA-PRIV' RULEARRAY 

C MOVE "KEY-MGMT ' RULEARRAY 
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C Z-ADD 2 RULEARRAYCNT 


CR KKK KKK EK KKK EK KKK EKER KEK ERE KK RK EK KERR EKER ER ERR RR ERE REE KERR ERE 


C* Call PKA_Key_Token_Build SAPI 


CR K KK KK KEKE KKK KKK KERR EKER KER EK ERK RK ER KERR EK ERR EKER REE EKER KERR ERR ERE 


C CALLP CSNDPKB (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C KEYSTRUCTLEN: 
C KEYSTRUCT: 

C KEYNAMEL: 

C KEYNAME: 

C ZERO: 

C NULLPTR: 

C ZERO: 

C NULLPTR: 

C ZERO: 

C NULLPTR: 

C ZERO: 

C NULLPTR: 

C ZERO: 

C NULLPTR: 

C TOKENLEN: 

C TOKEN) 

Cx a a ee ae * 

Cx »* Check the return code * 

Cx Fessseosssssssosessss secs * 

C RETURNCODE IFGT 0 

Cx fesssteeeence see eseee eee ce * 

Cx * Send failure message * 

Cx« Resoseesesssoosessesesscs * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDPKB' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 
CxSceSecsosSetescceusscasssscssessossSsSesssssscsisssseSscsees * 
Cx Build the certificate * 
Ckeceesssecessrssesosseese steal esos ce ese cseeSeesecseaseeceeces * 


Cx Get the private section length. The length is at position 11 
Cx of the token 


C EVAL MSB = TOKENARRAY (10+1) 
C EVAL LSB = TOKENARRAY(11+1) 
C MOVE LENGTH PRVSECLEN 


Cx Get the public section length. The length is at position 
Cx (11 + Private key section length). 


C EVAL MSB = TOKENARRAY(10 + PRVSECLEN + 1) 
Cc EVAL LSB = TOKENARRAY(11 + PRVSECLEN + 1) 
C MOVE LENGTH PUBSECLEN 

Cx Calculate the certificate section length 

C«* Cert Section length = Signature length (328) + 

Cx EID section length (20) + 

Cx Serial number length (12) + 

Cx Info subsection header length (4) + 
Cx Public Key section length + 

Cx Cert section header length (4) 

C EVAL LENGTH = 328 + 20 + 12 + 4 + PUBSECLEN + 4 
Cx Fill Certificate section header 

C MOVE TOKENLEN INDEX 

C EVAL TOKENARRAY (INDEX +1) = X'40' 

C EVAL TOKENARRAY (INDEX +2) = X'QQ' 

C EVAL TOKENARRAY (INDEX +3) = MSB 
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C EVAL TOKENARRAY (INDEX +4) = LSB 

Cx Fill in public key subsection 

C EVAL TOKENARRAY (INDEX +5) = X'41' 

C ADD 5 INDEX 

C Z-ADD dL I 

Cx Copy the public key section of the token into the public key 
Cx subsection of the certificate section. 

C I DOWLT PUBSECLEN 

C EVAL TOKENARRAY (INDEX + I) = 

C TOKENARRAY (PRVSECLEN + I + 8 + 1) 
C 1 ADD I I 

C ENDDO 

C EVAL INDEX = INDEX + PUBSECLEN - 1 
Cx Fill in Optional Information subsection header 

C Z-ADD 36 LENGTH 

C EVAL TOKENARRAY (INDEX +1) = X'42' 

C EVAL TOKENARRAY (INDEX +2) = X'QO' 

C EVAL TOKENARRAY (INDEX +3) = MSB 

C EVAL TOKENARRAY (INDEX +4) = LSB 

Cx Fill in Public Key Certficate EID 

C EVAL INDEX = INDEX + 4 

C EVAL TOKENARRAY (INDEX +1) = X'51' 

C EVAL TOKENARRAY (INDEX +4) = X'14' 
Cx Fill in Public Key Certficate Serial Number TLV 

C EVAL INDEX = INDEX + 20 

C EVAL TOKENARRAY (INDEX +1) = X'52' 

C EVAL TOKENARRAY (INDEX +4) = X'@C' 
Cx Fill in Signature Subsection 

C EVAL INDEX = INDEX + 12 

C EVAL TOKENARRAY (INDEX +1) = X'45' 

C EVAL TOKENARRAY (INDEX +3) = X'Q1' 

C EVAL TOKENARRAY (INDEX +4) = X'48' 

C EVAL TOKENARRAY (INDEX +5) = X'O1' 

C EVAL TOKENARRAY (INDEX +6) = X'O1' 
Cx Fill in private key name 

C EVAL INDEX = INDEX + 6 

C EVAL NAMEPTR1 = %ADDR(TOKENARRAY (INDEX +1)) 
C EVAL NAMEPTR2 = 

C %ADDR ( TOKENARRAY (PRVSECLEN+PUBSECLEN+12+1) ) 
C MOVEL NAME2 NAME1 

Cx Adjust token length 

C EVAL LENGTH = INDEX + 64 + 258 

C MOVE MSB TOKENARRAY (3) 

C MOVE LSB TOKENARRAY (4) 

C EVAL TOKENLEN = LENGTH 

Cx* a Sc pt cl i i * 


Cx »* Set the keywords in the rule array * 


MOVEL "RETAIN ' RULEARRAY 
MOVE ‘CLONE =! RULEARRAY 
Z-ADD 2 RULEARRAYCNT 


OOOO 
~ 


C CALLP CSNDPKG (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
ZERO: 
REGENDATA: 
TOKENLEN: 
TOKEN: 
TRANSPORTKEK: 
GENKEYLEN: 


DADADAAANAANAANAANANM 
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c GENKEY) 


Ck¥eeesessscee cee seeeeee es * 

Cx Check the return code * 

Ckscteeescece sees eee cess * 

C RETURNCODE IFGT 0 

Cx ececseseeseeee ee eee es * 

Cx * Send failure message * 

Cx a a a i sh * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDPKG' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 

Cx ee ee * 

Cx * Send success message * 

Cx ee * 

C MOVEL MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx 

(¥en ene eee eee see eee ee cesses # 

Cx Write certificate out to file * 

Ckeaee eee eee ewes see ewe ees # 

Cx ** Build path name 

C EVAL PATHLEN = %LEN(%TRIM(KEYNAMEPARM) ) 
C PATHLEN SUBST KEYNAMEPARM: 1 PATH 

C EVAL %SUBST (PATH: PATHLEN+1:4) = '.PUB' 
Cx 

Cx ** Open the file 

Cx 

C EVAL FILED = open(PATH: OFLAG) 
Cx« 

Cx ** Check if open worked 

Cx 

C FILED IFEQ -1 

Cx« 

Cx *x Open failed, send an error message 

Cx 

C MOVEL MSG (3) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ELSE 

Cx* 

Cx ** Open worked, write certificate out to file and close file 
Cx* 

C CALLP write (FILED: 

C GENKEY: 

C GENKEYLEN) 
C CALLP close (FILED) 

Cx« 

Cx ** Send completion message 

Cx 

C MOVEL MSG(4) MSGTEXT 

C EVAL %SUBST (MSGTEXT: 32: PATHLEN + 4) = 
C %SUBST(PATH: 1: PATHLEN + 4) 
C EXSR SNDMSG 

C ENDIF 

Cx 

C SETON 

Cx 


CK KAKA KEKE KKK KR KKK KKK ERK EKER ERK RK EK KERR EKER ER ERK ERE RK RR ERR 
Cx Subroutine to send a message 

CR KKK KKK KKK KK KKK KKK KER KER ERE RRR KER KERR EKER ER ERR REE RRR ERR 
C SNDMSG BEGSR 

C CALL "QMHSNDPM' 
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** 
CS 
Th 
Th 
Th 


Example: ILE C program for registering a public key hash 
Change this program example to suit your needs for registering a hash of a public key certificate. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


NDPKB failed with return/reason codes 9999/9999. 
e retained key was successfully created. 

e file could not be opened. 

e certificate was written to 


REGHASH 


Sample program to register the hash of a CCA public key 
certificate. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 
tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function 
of these program. All programs contained herein are 
provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 


these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: Stream file containing public key certificate 


Example: 
CALL PGM(REGHASH) PARM(CERTFILE) 


Note: This program assumes the card with the profile is 
already identified either by defaulting to the CRPO1 
device or by being explicitly named using the 
Cryptographic_Resource Allocate verb. Also this 
device must be varied on and you must be authorized 
to use this device description. 


The Common Cryptographic Architecture (CCA) verbs used are 
PKA_Public_Key Hash Register (CSNDPKH) and One_Way_Hash 
(CSNBOWH) . 


Use these commands to compile this program on iSeries: 

ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(REGHASH) SRCFILE(SAMPLE) 

CRTPGM PGM(REGHASH) MODULE (REGHASH) 
BNDDIR(QCCA/QC6BNDDIR) 
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/* 
/* Note: Authority to the CSNDPKH and CSNBOWH service programs 
/* in the QCCA library is assumed. 
/* 
peetaeseeesene ses eessSS ee eae ase ae a a Ss eo ees sae a sae eas 
#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 
int main(int argc, char *argv[]) 
{ 
| ee ee ee 
/* Declares for CCA parameters 
/ #sacssceeascassssaseeseess see sts sense ss sss ssesSess asses Ssseeseeass 
long return_code = Q; 
long reason_code = Q; 
long exit_data_length = 0; 
char exit_data[4]; 
char rule_array[24]; 
long rule_array_count; 
long token_len = 2500; 
char token[2500]; 
long chaining_vector_length = 128; 
long hash_length = 20; 
long text_length; 
unsigned char chaining _vector[128]; 
unsigned char hash[20] ; 
| Reeeneees=eeassansoeesscsessesse ese essos aaseceeoessaes2—>-esesoee55 
/* Declares for working with a PKA token 
JxGe x ceaesa as Ss sas aes sen seaee ses eea setae s Ses sees eee ee= seas Saeeas 
long pub_sec_len; /* Public section length 
long cert_sec_len; /* Certificate section length 
long offset; /* Offset into token 
long tempOffset; /* (Another) Offset into token 
char name[64] ; /* Registered key name 
long count; /* Number of bytes read from file 
FILE «fp; /* File pointer 
if (arge < 2) /* Check the number of parameters passed 
printf("Need to enter a public key name\n"); 
return 1; 
} 
memset(name,' ',64); /* Copy key name (and pad) to a 64 byte 
/* field. 
memcpy (name, argv[1],strlen(argv[1])); 
fp = fopen(argv[1],"rb"); /* Open the file for reading 
if (!fp) 
{ 
printf("File %s not found.\n",argv[1]); 
return 1; 
} 
memset (token,0,2500) ; /* Initialize the token to 0 
count = fread(token,1,2500,fp); /* Read the token from the file 
fclose(fp); /* Close the file 


/* Determine length of token from length 
/* bytes at offset 2 and 3. 
token_len = ((256 * token[2]) + token[3]); 


if (count < token_len) /* Check if whole token was read in 
{ 
printf("Incomplete token in file\n"); 
return 1; 
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*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 


*/ 


*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 


*/ 


} 


[KERR KER AKER AKER AK EKA KKK KK EIR KER KKK A KEI KKK KKK AKER AKER AK | 


/* Find the certificate offset in the token */ 
/* x/ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* x/ 


[KERR KER KKK AK ERIK EKA K KEK KEIR KER KKK IKEA IKE AK KEKE AKER AK | 


pub_sec_len = ((256 * token[10]) + token[11]); 


offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section 

/* length from the length bytes at 

/* offset 2 of the section. 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 
tempOffset = offset + 4; /* Set offset to first subsection 


/* Parse each subsection of the certificate until the */ 
/* signature subsection is found or the end is reached.*/ 
/* (Identifier for signature subsection is Hex 45.) */ 


while(token[tempOffset] != 0x45 && 
tempOffset < offset + cert_sec_len) 


{ 

tempOffset += 256 * token[tempOffset + 2] + token[tempOffset+3]; 

} 
[¥onenetesrsesaaasaeea se dassaSeeeesaeescoeseeasaae ses «/ 
/* Check if no signature was found before the end of */ 
/* the certificate section. */ 
| ee ee ee ee eee eee ee ee eee ee «/ 
if (token[tempOffset] != 0x45) 

{ 

printf("Invalid certificate\n"); 

return 1; 


} 


[ERR KER KKK AKER IKEA KKK KEIR KEK KKK IKE KAKA KEK AKER AKER KEKE | 

/* Hash the certificate */ 

[RRR KKK AKER AKER A KKK KKK KK AK KKK KKK KKK KKK AK KEK AKER AKER AKER | 

text_length = tempOffset - offset + 70; /* Text length is length 
/* of certificate subsection. 


memcpy ((void*)rule_array,"SHA-1 ",8); /* Set rule array 
rule_array_count = 1; 

chaining_vector_length = 128; 

hash_length = 20; 


CSNBOWH( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&text_length, 
&token[offset], 
&chaining_vector_length, 
chaining_vector, 
&hash_length, 
hash); 


if (return_code != 0) 
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printf("One_Way_Hash Failed : return reason %d/%d\n", 
return_code, reason_code); 
return 1; 


} 


[BERR KER KKK A KERIKERI KKK EKA A KEI KK A KEI KER AKER | 


/* Register the Hash */ 
[RRR KER KKK AKER A KKK KKK KK IK KKK KKK A KKK A KKK KKK KKK AKER KKK | 
/* Set the rule array x/ 


memcpy ((void*)rule_array,"SHA-1 CLONE ",16); 
rule_array_count = 2; 
/* Build the name of the retained +*/ 
/* key from the file and "RETAINED"*/ 
memcpy (&name[strlen(argv[1])],".RETAINED",9) ; 


CSNDPKH( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
name, 
&hash_length, 
hash) ; 


if (return_code != 0) 


printf("Public Key Register_Hash Failed : return reason %d/%d\n", 
return_code, reason_code) ; 
return 1; 


} 


name[strlen(argv[1]) + 9] = 0; /* Convert name to a string */ 
printf("Hash registered for %s.\n",name) ; 


} 


Example: ILE RPG program for registering a public key hash 
Change this program example to suit your needs for registering a hash of a public key certificate. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DARK RKKKKK KKK ERK KK EK KKK RRR KKK KEK KK ERR KKK KEK KEKE RK KR ERK KR RRERREKER A 
D* REGHASH 

Dx« 

D* Sample program to register the hash of a CCA public key 

D* certificate. 

Dx« 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

D* Parameters: Stream file containing public key certificate 
Dx 
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D* Example: 

D* CALL PGM(REGHASH) PARM(CERTFILE) 

Dx« 

Dx Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(REGHASH) SRCFILE(SAMPLE) 

D* CRTPGM PGM(REGHASH) MODULE (REGHASH) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

Dx Note: Authority to the CSNDPKH and CSNBOWH service programs 
Dx in the QCCA library is assumed. 

Dx 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* PKA Public_Key Hash Register (CSNDPKH) and One Way Hash 
C* (CSNBOWH) . 


Dx« 

DA KRKKKKKKK KKK KKK KEK KKK ERK RRR KERR KERR RRR RRR KR ER RRR ERR ERE ER ERRRER 
Dkeeeeeesaaetae sles see ea see oee se see eee See eee sae 
D* Declare variables used by CCA SAPI calls 

Deer ecesosscsscescusceeeeeseessososseosessessesessSoe ss scse 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx xx Exit data length 

DEXTTDATALEN Ss 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

Dx ** Token and array for subscripting token 
DTOKE DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx ** Chaining vector length 
DCHAINVCTLEN S 9B 0 INZ(128) 

Dx ** Chaining vector 

DCHAINVCT S 128 

Dx ** Hash length 

DHASHLEN S 9B 0 INZ(20) 

Dx ** Hash 

DHASH S 20 

Dx ** Text length 

DTXTLENGTH S 9B 0 

Dx xx Name of retained key 

DNAME S 64 

Dx ** Structure used for aligning 2 bytes into a 
Dx xx 2 byte integer. 

DLENSTRUCT DS 2 

DMSB 1 1 

DLSB 2 2 

DLENGTH 1 2B 0 

Dx« 

Dx xx Certificate section length 
DCRTSECLEN S 9B 0 

D* ** Public key section length 
DPUBSECLEN S 9B 0 

Dx ** Index into PKA key token 
DTKNINDEX S 9B 0 

Dx ** Index into PKA key token 
DTMPINDEX S 9B 0 

Dx ** File descriptor 

DFILED S 9B 0 

Dx ** File path and path length 
DPATH S 80 INZ(*ALLX'00') 
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DPATHLEN Ss 9B 0 


Dx ** Open Flag - Open for Read only 
DOFLAG S 101 0 INZ(1) 
Dx« 


DARK RKKKKK KK KER KKK KKK KEKE RK KKK ERK KEKE KEK KKK KK KEKE KKK ERK KERR 


D* Prototype for PKA _Public_Key_ Hash Register (CSNDPKH) 


DA RRRKKKKK KKK ERK KKK KKK KERR KERR RRR ERE R KEK RR ER KERR ERE RE RERER 


DCSNDPKH PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
DRARRYCT 9B 0 
DRARRY 16 
DKYNAM 64 
DHSHL 9B 0 
DHSH 20 OPTIONS (*VARSIZE) 
Dx« 


DARK RK KKK KKK KER KKK EK KKK RRR KKK KERR RRR KEK KERR KKK KER KERR ERK KR EKER 


D* Prototype for One _Way Hash (CSNBOWH) 


DA KRKKKKKKKK KER KKK ERK KEKE RRR KERR RRR RE RRR KKK ER RRR ER KERR ERR 


DCSNBOWH PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
DRARRYCT 9B 0 
DRARRY 16 
DTXTLEN 9B 0 
DTXT 500 OPTIONS (*VARSIZE) 
DCHNVCTLEN 9B 0 
DCHNVCT 128 
DHSHLEN 9B 0 
DHSH 20 

Dx 

Dx« 


DAKAR KKKKK KKK ERK KK KEK KKK ERK KKK R KKK RRR RRR R KERR ER KERR EKER RERERER 


Dx Prototype for open() 


DAK RRKKKKK KKK ERK KKK KKK KER KK KEKE RK KEKE RK KKK KKK KER KERR RKR KK RRR 
Dx value returned = file descriptor (OK), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B 0 VALUE 

D« (OPTIONAL) mode - access rights 

D 10U @ VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx 


DA KRKKKKKK KKK ERK K KEK K KERR KEK KERR KEK REE KERR KERR RRR KR RE RRR RRR KR ERR KER ERKERERE 


Dx Prototype for read() 


DA RRRKKKKK KK KER KKK EK KKK RRR KKK ERK KEKE KEK KR KKK KEKE RE RR RER KKK EREKE 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be read 

D 9B 0 VALUE 

Dx 


DA RRKKKKK KKK KER KKK KE KK KERR KR KERR KEK RRR RRR RRR KERR ERR KR RE RRR RRR KR ER RR RERKERERE 
D* Prototype for close() 

DA KRKKKKKKKK KEKE KKK KKK KR KEK KER KER RRR RK KR RR KR REE R KERR ER RRR RRR KERR RR ERKERERE 
Dx value returned = 0 (OK), or -1 

Dclose PR 9B 0 EXTPROC('close') 
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D« File descriptor returned from open() 


D 9B 0 VALUE 

Dx« 

DxeSS Sere ee ees ees sessee ee eee eee sees eceee sere See eee ee eee see eee 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Peet eee as nae ese saetees se cee eee se eee eee eee See See eee se oes 
DMSG S 75 DIM(6) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 80 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* *) 
DSTACKCOUNTER S 9B © INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(O) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CR KKK K KKK KKK KK KKK KR EKER KEK ERK KK KK ER KKK EK KE KK EKER KERR ER ERE RK ERR ERE 
Cx START OF PROGRAM * 
Cx« * 
C *ENTRY PLIST 

C PARM FILEPARM 50 


CK KKK KKK KKK KK KKK KR EKER KEK ERK KKK KEK KKK RK KERR EKER KERR ER ERK REKERRERE 


Cx Open certificate file 
CR KKK KK KKK KK KK KKK KR EKER KER ERK KK EKER KR KEKE ER EK ERR RR ERE RK EK ERR ERE 


Cx« tosnseeseccocecseeseees * 

Cx  »** Build path name * 

Cx* Coscis ccna cao ome! * 

¢ EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx Peseta see secs eee seeue * 

Cx * Open the file * 

Cx* Se a Se etm * 

C EVAL FILED = open(PATH: OFLAG) 

Cx« Cecaaicnnciasonaeenmasiaaia * 

Cx »* Check if open worked * 

Cx« Lasoaseaccoacwaceae cess * 

C FILED IFEQ -1 

Cx* Pipes oee RS eee eee eee eee ee ces * 

Cx * Open failed, send an error message * 

Cx eeSsesessacossSsoacoasssoseoseeSsece= * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx* 

C ENDIF 

C* aaa aha es lara et ele a ee * 
Cx * Open worked, read certificate and close the file * 
Cx WeeceeeS saa soa Sea seSSeeS Sessa ses aa == Sasa eeaa oe ae = * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx* 

Cx Necisoseseeateseeeesesesceee ese ns ee see * 

Cx * Check if read operation was OK * 

Cx HeSsessssecsseteoceecossessseu assesses * 

C TOKENLEN IFEQ -1 

C MOVEL MSG(2) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 


Chapter 5. 4758 Cryptographic Coprocessor for iSeries 


213 


Cx KeccSeesees somes e cones see sesececcce * 
Cx * Check if certificate length is valid * 
Cx * The length bytes start at position 3 * 
Cx« cease eeeceesesaceesseescaeeaaSeeeseseee * 

C EVAL MSB = TOKENARRAY (3) 
C EVAL LSB = TOKENARRAY (4) 
C LENGTH IFLT TOKENLEN 

Cx WeSssessosessessestessoeeescess sSssss * 
Cx * Certificate length is not valid * 
Cx Ressvscesereesseslessoseossoceescose * 

C MOVEL MSG (3) MSGTEXT 
C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 


CR K KKK KKK KKK KKK KKK EKER KER ERE KK EKER KERR EKER ERE RE RR EKER KERR ERR 
Cx Find the certificate in the token 

Cx« 

Cx The layout of the token is 

Cx 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 3 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

Cx« 

Cx Note: 1 is added because RPG arrays start at 1. 

CK KKK KKK KKK KK KKK KR KK EK KEK ERE KK EKER KEK RRR KERR EKER KERR EKER ERR EKER 


C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Cx« 

Cx« eeesossoseae poe eseesses eee sake a ceoeeeeeeee * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

Cx« tessecesoeSsesceeesaeensaeseccessseeeeSe ee * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 

C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 

C EVAL CRTSECLEN = LENGTH 

C EVAL TMPINDEX = TKNINDEX + 4 

Cx« 

Cx ceeeoctosacseesecse se cescseeec este ccceseescaeesescecouecs * 
Cx * Parse each subsection of the certificate until the * 
Cx * Signature subsection is found or the end is reached.* 
Cx * (Identifier for signature subsection is Hex 45.) * 
Cx« tone cee eee ces eeeee noes onesSeeaReseeSesSeeseeoesoeceos * 
C DOW (TOKENARRAY (TMPINDEX) <> X'45') AND 
C (TMPINDEX < TKNINDEX + CRTSECLEN) 
C EVAL MSB = TOKENARRAY(TMPINDEX + 2) 

C EVAL LSB = TOKENARRAY(TMPINDEX + 3) 

C TMPINDEX ADD LENGTH TMPINDEX 

C ENDDO 

Cx* 

Cx« esse oeeeeS eee eee se eees sae ee Seeks Sees eSeeeesesesscease] * 
Cx * Check if no signature was found before the end of * 
Cx * the certificate section. * 
Cx eee se soe ea Cone eee eee anemia cee amiaee * 
C IF TOKENARRAY (TMPINDEX) <> X'45' 

C MOVEL MSG (4) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 


CR KKK KKK KKK KK KKK KR KK EK KKK ERE KK EK ERK KK RK KERR EKER KERR EKER KERR ERR RERE 
Cx Hash the certificate 
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CR KKK KKK KKK KK KKK KKK KEK KEK ERK KKK KER KKK EK KKK EKER KERR ERE RE RRR RR ERE 


Cx* 
Cx* 
Cx* 
C 

Cx 
Cx* 
Cx* 
C 

C 

Cx« 
Cx* 
C* 


a 


OOOO: A:0°O:0 


Kee eee ee ee * 
* Calculate the length to hash * 
Kee ee ee ee ee * 
EVAL TXTLENGTH = TMPINDEX - TKNINDEX + 70 
Kee eee * 
* Set the keywords in the rule array * 
Kee ee ee ee ee * 
MOVEL "SHA-1 RULEARRAY 
Z-ADD 1 RULEARRAYCNT 
Kee eee * 
* Call One Way Hash SAPI * 
Kee eee ee ee * 
CALLP CSNBOWH (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
TXTLENGTH: 
TOKENARRAY (TKNINDEX) : 
CHAINVCTLEN: 
CHAINVCT: 
HASHLEN: 
HASH) 
Kee eee - - - - -  - - * 
* Check the return code * 
Kee ee * 
RETURNCODE IFGT 0 
Kee ----- * 
* Send failure message * 
Kee ---- - - - - - - -  - * 
MOVEL MSG(5) MSGTEXT 
MOVE RETURNCODE FAILRETC 
MOVE REASONCODE FAILRSNC 
MOVEL "CSNBOWH' SAPI 
EXSR SNDMSG 
RETURN 
ENDIF 


CR KKK KK KKK KKK KEKE KR EKER KER ERE KK RK ERK RRR RE RER ERR RR ERE RR RR ERR 


Cx Register the certificate hash 
CK KKK KK KKK KK KKK KR EKER KEK ER KKK EKER KKK RK KERR ERE RR RR ERE RARER ERR ERE 


Cx« 
Cx* 
Cx* 


Kew we ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 
* Set the keywords in the rule array 
Kee eee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 
MOVEL "SHA-1 
MOVE ‘CLONE =! 
Z-ADD 2 
ee 


RULEARRAY 
RULEARRAY 
RULEARRAYCNT 


Kee eee * 
EVAL %SUBST(NAME: 1: PATHLEN) = 
%SUBST(PATH: 1: PATHLEN) 
EVAL %SUBST (NAME: PATHLEN+1:9) = '.RETAINED' 
Kew ewe eee ee ee ee ee ee ee eee ee ee ee ee ee ee 
* Call PKA Public Key Hash Register * 
ee 
CALLP CSNDPKH (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
NAME: 
HASHLEN: 
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c HASH) 


CX: Wesssscecssesssoseceeesce * 

Cx »* Check the return code * 

C8 Beeseesscsseossssssesnece * 

C RETURNCODE IFGT 0 

Cx Keeeeese esses seen eeese * 

Cx * Send failure message * 

Cx Fests see sesee eee stecee ae * 

C MOVEL MSG(5) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDPKH' SAPI 

C EXSR SNDMSG 

C ELSE 

Cx Receeees tee eee eee eee ee * 

Cx * Send success message * 

Cx Pecesere cose seesdsseases * 

C MOVEL MSG (6) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 41: PATHLEN + 9) = 
C %SUBST(NAME: 1: PATHLEN + 9) 
C EXSR SNDMSG 

C ENDIF 

Cx« 

C SETON LR 
Cx« 


CARR KK KK KEKE KKK KKK KKK KR ERK ER EK ERK K EKER KEKE RR ER ERE RR ERE RR RR ERR 


Cx Subroutine to send a message 
CR KKK KKK EK KKK KEKE KKK KEK KEK ERE KK EKER KKK EKER ERE RE RR ERE RE RR ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 

The file could not be opened. 

There was an error reading from the file. 

The length of the certificate is not valid. 

The certificate is not valid. 

CSNBOWH failed with return/reason codes 9999/9999. 
The hash was successfully registered as 


Example: ILE C program for registering a public key certificate 
Change this program example to suit your needs for registering a public key certificate. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


[#esessSeseees ese sestessenseseseeeeesee Sees eeeseoee snes seeoesessee oe */ 
/* REGPUBKEY x/ 
/* x/ 
/* Sample program to register a CCA public key certificate x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE */ 
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/* 


ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 


/* these programs and files. x/ 
/* */ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. «/ 
/* */ 
/* Parameters: Stream file containing public key certificate */ 
/* x/ 
/* Example: */ 
/* CALL PGM(REGPUBKEY) PARM(CERTFILE) */ 
/* */ 
/* x/ 
/* Note: This program assumes the card with the profile is x/ 
/* already identified either by defaulting to the CRPO1 x*/ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* */ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* PKA_Public_Key Register (CSNDPKR). x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: x/ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(REGPUBKEY) SRCFILE (SAMPLE) */ 
/* CRTPGM PGM(REGPUBKEY) MODULE (REGPUBKEY) */ 
/* BNDDIR(QCCA/QC6BNDDIR) */ 
/* x/ 
/* Note: Authority to the CSNDPKR service program */ 
/* in the QCCA library is assumed. */ 
/* x/ 
Jeoses seesss sos ssessessuecucasesscssasessessesasSssssescelessceessse ss */ 
#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 

int main(int argc, char *argv[]) 

- ea a eS og ee a a */ 
/* Declares for CCA parameters */ 
| Ramecee see sas a acasas sarees anes aso ee se esas eee eae a ee ee */ 
long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 0; 

char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 
/eesssesesssessossessckS tS se sses sh eheest assesses se sesseeesessess */ 
/* Declares for working with a PKA token */ 
/ $eneeeae ese seeeeherasess seesee sete es ceeecesseees Sseesesensesseee «/ 
long pub_sec_len; /* Public section length */ 
long cert_sec_len; /* Certificate section length */ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
char name[64] ; /* Registered key name */ 
long count; /* Number of bytes read from file */ 

FILE «fp; /* File pointer */ 

if (argc < 2) /* Check the number of parameters passed */ 

{ 


printf("Need to enter a public key name\n"); 
return 1; 
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} 


memset(name,' ',64); /* Copy key name (and pad) to a 64 byte */ 
/* field. */ 
memcpy (name, argv[1],strlen(argv[1])); 


fp = fopen(argv[1],"rb"); /* Open the file for reading x/ 
if (!fp) 
{ 
printf("File %s not found.\n",argv[1]); 
return 1; 
} 
memset (token,0,2500) ; /* Initialize the token to 0 */ 
count = fread(token,1,2500,fp); /* Read the token from the file */ 
fclose(fp); /* Close the file */ 
/* Determine length of token from length */ 
/* bytes at offset 2 and 3. */ 
token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in */ 
{ 
printf("Incomplete token in file\n"); 
return 1; 
} 
[BRK RK ERR KKK KER KKK K KK AKK EA KKK KKK KKK AKER AKER AKER | 
/* Find the certificate length in the token x/ 
/* x*/ 
/* The layout of the token is */ 
/* */ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 2 x/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section */ 


[BRK RK ER KKK A KER AKER KKK KK AK KAKA KKK AREA AREA KERR | 

pub_sec_len = ((256 * token[10]) + token[11]); 

offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 
/* Determine certificate section */ 
/* length from the length bytes at */ 
/* offset 2 of the section. */ 

cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 


[BERR KER AKER AKER IKK A KKK AREA KKK KKK IKEA KK EAR KEK AKER AKER AKER | 


/* Register the Public Key */ 
[RRR KER KKK A KEK K KKK KAKI KKK AKER A KKK A KK A KKK KKK AKER KKK | 
memcpy((void*)rule_array,"CLONE ",8); /* Set rule array */ 


rule_array_count = 1; 
/* Build the name of the retained */ 
/* key from the file and "RETAINED"*/ 
memcpy (&name[strlen(argv[1])],".RETAINED",9) ; 


CSNDPKR( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
name, 
&cert_sec_len, 
&token[offset]); 


if (return_code != Q) 
{ 
printf("Public Key Register Failed : return reason %d/%d\n", 
return_code, reason_code); 
return 1; 
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} 


name[strlen(argv[1]) + 9] = 0; /* Convert name to a string */ 
printf("Public key registered for %s.\n",name) ; 


} 


Example: ILE RPG program for registering a public key certificate 
Change this program example to suit your needs for registering a public key certificate. 


Note: Read the|/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKKKK KERR KKK ERK KEKE RRR KE KKK RRR KERR ERK RRR ERR RRR KERR ERR KERR 
D* REGPUBKEY 

Dx« 

D* Sample program to register a CCA public key 

D* certificate. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

D* Parameters: Stream file containing public key certificate 
Dx« 

D* Example: 

D* CALL PGM(REGPUBKEY) PARM(CERTFILE) 

Dx« 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(REGPUBKEY) SRCFILE(SAMPLE) 
D* CRTPGM PGM(REGPUBKEY) MODULE (REGPUBKEY) 


Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx 

D* Note: Authority to the CSNDPKR service program 
Dx in the QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* PKA Public_Key Register (CSNDPKR). 


Dx 

DA KRKKKKKK KKK KEK KKK KKK KK ERK KKK KKK KKK KEK KEKE KK KR ER KEK RRR KEK RRR EKER 
Dxee eee eeeoSoeeee eee cee eee esas eee cee eee eee sees 
D* Declare variables used by CCA SAPI calls 

Dees eeoSeesees ese osaoseSsseSeea sae Se Sas ss 55 == SSeS 555SSS55 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT > 9B 0 

Dx ** Rule array 
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DRULEARRAY S 16 


Dx ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

Dx ** Token and array for subscripting token 
DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx ** Name of retained key 

DNAME S 64 

Dx xx Structure used for aligning 2 bytes into a 
Dx *x 2 byte integer. 

DLENSTRUCT DS 2 

DMSB 1 1 

DLSB 2 2 

DLENGTH 1 2B 0 

Dx *x Certificate section length 
DCRTSECLEN S 9B 0 

Dx ** Public key section length 
DPUBSECLEN S 9B 0 

Dx ** Index into PKA key token 
DTKNINDEX S 9B 0 

Dx ** Index into PKA key token 
DTMPINDEX S 9B 0 

Dx ** File descriptor 

DFILED S 9B 0 

Dx ** File path and path length 
DPATH S 80 INZ(*ALLX'00') 
DPATHLEN S 9B 0 

Dx ** Open Flag - Open for Read only 
DOFLAG S 101 @ INZ(1) 

Dx 


DAKAR KKKKK KKK ERK KEKE KKK KERR KERR ERK RRR ER KERR KERR ERR ER KER RRERREERK 


D* Prototype for PKA_Public_Key Register (CSNDPKR) 


DARK A KK KKK KK KER KKK EK KKK ERK KKK ERK KEKE RK KERR KK KR ER RE KREKR KK KERRREKE 


DCSNDPKR PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
DRARRYCT 9B 0 
DRARRY 16 
DKYNAM 64 
DCRTLEN 9B 0 
DCRT 500 OPTIONS (*VARSIZE) 
Dx 


DA KRKKKKKKK KK ERK KKK KKK KERR KERR KERR ERR RRR RRR KR ER KKK ER KERR RRR 


D* Prototype for open() 


DA KRRKKKKK KKK KKK KK KEK KKK RRR KKK KERR KK RRR KERR KEK KR ER KKK ERK KERR REKEK 
D« value returned = file descriptor (OK), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

D* Open flags 

D 9B @ VALUE 

D« (OPTIONAL) mode - access rights 

D 10U @ VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U @ VALUE OPTIONS (*NOPASS) 
Dx« 


DA RRKKKKKKKK KEK KKK KERR RRR KERR RRR RRR RR KR ER KER RRR RRR EER RRR R KEKE ER KERR ERR EE 


D* Prototype for read() 


DA RRA KKKKK KK KER KKK KKK KK ERK KKK KERR KERR RK KERR KKK KER RK RRR KKK ERREKEK 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
D« File descriptor returned from open() 

D 9B @ VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
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D* Length of data to be read 

D 9B 0 VALUE 

Dx 

DA RRKKKKKKK KEKE KKK KEK KKK RRR KER KKK KERR KR RR KER RRR KER ER KERR RRR KR ERR RR ERR RRERR 
D* Prototype for close() 

DA KRKKK KKK KKK RK KKK ERK KERR KKK KK KK KER KKK RR K RRR KR KK RR KR ERK KR ERR RR RKER KR ER 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 

Deeeeeeaesaas ese scetese secs s oe Sas eee see eee ete se cee ee saben = 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

De ee ee ee 
DMSG 5 75 DIM(5) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(75) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ~) 
DMESSAGEFILE Ss 21 INZ(' ') 
DMSGKEY S 4 INZ(' ") 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY Ss 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx 

CR KKK KK KKK KKK KEK KEK RE KERR ER ERE KK EKER KKK EKER EK ERR RR ER ERK RKERRERE 
Cx START OF PROGRAM * 
Cx * 
C *ENTRY PLIST 

C PARM FILEPARM 50 


CARR KKK KEKE KKK KEKE KR EKER KER EKER KEK ERK RR EKER RE ERERKERERERE REE ERRERE 


Cx Open certificate file 
CR KKK KKK KKK KK KKK KKK KEK KKK ERK KK RK ER KKK RK KERR ERE RR RR ER ERE RK ERR ERE 


Cx Hesbessssseassneseeess * 

Cx  »** Build path name * 

Cx Peso e sees esee sees e ees * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx Psesesssese dese sseess * 

Cx  »* Open the file * 

Cx Pee oe sess ee eee eee * 

C EVAL FILED = open(PATH: OFLAG) 

Cx ee ee ee ee * 

Cx »* Check if open worked * 

Cx Pik hee eco eee eee se ese oe * 

C FILED IFEQ -1 

Cx Meese sseesea = saa Seas see Seosee—=so== * 

Cx * Open failed, send an error message * 

Cx Mecseseeseessessoe cesses see eoee eee Ss * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx 

C ENDIF 

Cx eae ae = ae a ae aaa a SaaS aS se Sa eS = ea = = * 
Cx * Open worked, read certificate and close the file * 
Cx KeeeceesccostessscecSeeecste seen sees eesesseee sees * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx« 

Cx KossosiassSsosscesessesSsceesseesseusssce * 
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Cx * Check if read operation was OK * 


Cx* Lecce ace eco tech ace eat ceee a eases a same ae * 

C TOKENLEN IFEQ -1 

C MOVEL MSG (2) MSGTEXT 
C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* 

Cx« tossotaecneaseesaceessosscese ce sceeceese * 
Cx * Check if certificate length is valid * 
Cx * The length bytes start at position 3 * 
Cx* Pec cascence cea Rowe aan ee eae eee em ee * 

¢ EVAL MSB = TOKENARRAY (3) 
C EVAL LSB = TOKENARRAY (4) 
C LENGTH IFLT TOKENLEN 

Cx* oases eee mia eee ote oe eee Sea * 
Cx * Certificate length is not valid * 
Cx* Ce eee ee eee * 

C MOVEL MSG (3) MSGTEXT 
C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx« 


CR KKK KKK KKK KK KKK KKK KEK KEK ERR KKK KERR KR RK KERR ERE RR RR EKER KERR ERR ERE 
Cx Find the certificate in the token 

Cx 

Cx The layout of the token is 

Cx« 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 3 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

Cx« 

Cx Note: 1 is added because RPG arrays start at 1. 

CR K KK KKK KKK KK KEKE KKK KER KER ERE KK RK EKER EK ERR ERE RRR ERE REE ERR 


C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Cx« 

Cx* Poaceae nese eee ea See ee eee eo ne soe se * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

Cx* (eccca sce eee e etek eee cece ee et eeweee * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 
C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 
C EVAL CRTSECLEN = LENGTH 

Cx 


CR K KKK KKK KKK KK EKER KKK ERK ER ERE RRR KER KERR EK ERR ERE RR RR ERE RRR ERREERE 


Cx Register the public key 


CR K KKK KKK KKK KK KKK KKK KER KEK ERE KK KK ER KERR RK ERR ERE RK RR EKER KERR ERR ERE 


Cx (oe aes == sa ee ee eee ee = a aa ea aa e= == = = Sea = * 

Cx »* Set the keywords in the rule array * 

Cx esses celea cease sosessah sec sse sees eeeestss * 

C MOVEL ‘CLONE =! RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

Cx SS eS ee ee ee eee * 

C* »* Build the key name (FILENAME.RETAINED) * 

Cx Pessse sesso se sees sse sae sseeeseea se eet eeess * 

C EVAL %SUBST (NAME: 1: PATHLEN) = 

C %SUBST(PATH: 1: PATHLEN) 
C EVAL %SUBST (NAME: PATHLEN+1:9) = '.RETAINED' 
Cx Pie eons eesesesewsewer eae eneeeee * 

Cx * Call PKA Public Key Register * 

Cx Pisces ree esse ones ee ceecesees * 
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** 


(RETURN 
REASON 
EXITDA 
EXITDA 
RULEAR 
RULEAR 
NAME: 
CRTSEC 
TOKENA 


MSGTEXT 
FAILRET 
FAILRSN 


MSGTEXT 


CODE: 
CODE: 
TALEN: 
TA: 
RAYCNT: 
RAY: 


LEN: 
RRAY (TKNINDEX) ) 


C 
C 


%SUBST(MSGTEXT: 41: PATHLEN + 9) = 
%SUBST(NAME: 1: PATHLEN + 9) 


C CALLP CSNDPKR 
C 

C 

C 

C 

C 

C 

C 

C 

Ce -casseeceeceso-SaeaSo=2S=5 

Cx * Check the return code 

Cx teeeesecesetabese esse seces 

C RETURNCODE IFGT 0 

Cx* tonaeaseecaenacesesseaaae * 

Cx * Send failure message * 

C* esp asic ors a ar * 

C MOVEL MSG (4) 
C MOVE RETURNCODE 
C MOVE REASONCODE 
C EXSR SNDMSG 
C ELSE 

Cx« Semca cana ake a ci aie a * 

Cx * Send success message * 

Cx« Ljvosscesaenacuaaeeosaae * 

C MOVEL MSG (5) 
C EVAL 

C 

C EXSR SNDMSG 
C ENDIF 

Cx* 

C SETON 

Cx* 


LR 


CRRA KKK KKK KKK KKK RE KEK KEK ER KKK EKER KEK KEKE KK ER ERE RR ERE RRR ERR ERE 


Cx Subroutine to send a message 
CRRA KKK KKK KKK KKK KEKE KE RK ER ERE KK RK ERK RR EK ERR ERE RRR KEKE RK REKERRE ERE 


C 


AMAADAIAMAAaAaAAaAa 


SNDMSG 


BEGSR 
CALL 

PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
ENDSR 


The file could not be opened. 
There was an error reading from the file. 

The length of the certificate is not valid. 
CSNDPKR failed with return/reason codes 9999/9999. 
The hash was successfully registered as 


"QMHSNDPM! 


MESSAGE 
MESSAGE 
MSGTEXT 
MSGLENG 
MSGTYPE 
STACKEN 
STACKCO 
MSGKEY 

ERRCODE 


ID 
FILE 


TH 


TRY 
UNTER 


Example: ILE C program for certifying a public key token 
Change this program example to suit your needs for certifying a public key token. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 


HiHtiMtctith deren ee en mE Renee eee ene */ 
CERTKEY x/ 
x/ 

Sample program to certify a CCA public key certificate to be x/ 
used for master key cloning. x/ 
x/ 

COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 x/ 
x/ 
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/* 


/* consideration. These examples have not been thoroughly 

/* tested under all conditions. IBM, therefore, cannot 

/* guarantee or imply reliability, serviceability, or function 
/* of these program. All programs contained herein are 

/* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
/* these programs and files. 

/* 

/* 

/* Note: Input format is more fully described in Chapter 2 of 
/* IBM 4758 CCA Basic Services Reference and Guide 

/* (SC31-8609) publication. 

/* 

/* Parameters: FILENAME - File containing public key token 
/* RETAINED_KEY_NAME - Name of key to certify token 
/* 

/* Example: 

/* CALL PGM(CERTKEY) PARM(MYKEY.PUB CERTKEY) 

/* 

/* 

/* Note: This program assumes the card with the profile is 

/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource Allocate verb. Also this 

/* device must be varied on and you must be authorized 

/* to use this device description. 

/* 

/* The Common Cryptographic Architecture (CCA) verbs used are 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 
#i 
#i 
#i 


This material contains programming source code for your 


Digital Signature Generate (CSNDDSG) and One Way Hash (CSNBOWH) . 


Use these commands to compile this program on iSeries: 

ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(CERTKEY) SRCFILE (SAMPLE) 

CRTPGM PGM(CERTKEY) MODULE(CERTKEY) 
BNDDIR(QCCA/QC6BNDDIR) 


Note: Authority to the CSNDDSG and CSNBOWH service programs 
in the QCCA library is assumed. 


nclude <stdio.h> 
nclude <string.h> 
nclude "csucincl.h" 
nclude "decimal .h" 


extern void QDCXLATE(decimal (5,0), char *, char*, char *); 
#pragma linkage (QDCXLATE, OS, nowiden) 


int main(int argc, char *argv[]) 


{ 


long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 0; 

char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 

long chaining_vector_length = 128; 
long hash_length = 20; 

long text_length; 

unsigned char chaining_vector[128]; 
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unsigned char hash[20] ; 
long signature_length = 256; 
long signature_bit_length; 


| eee ee ae ee eee */ 
/* Declares for working with a PKA token */ 
/ResSseessesesssscsseusetecetsesscset sees sees case sessasesessess */ 
long pub_sec_len; /* Public section length */ 
long cert_sec_len; /* Certificate section length */ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
long tempLength; /* Length variable x/ 
char name[64] ; /* Private key name */ 
char SAname[64]; /* Share administration or certifying */ 

/* key name. */ 
char SAnameASCII[64]; /* Share admin key name in ASCII */ 
long SAname_length = 64; /* Length of Share admin key name */ 
long count; /* Number of bytes read from file */ 
decimal(5,0) xlate_length = 64; /* Packed decimal variable x/ 

/* needed for call to QDCXLATE. */ 
FILE «fp; /* File pointer */ 
if (argc < 3) /* Check the number of parameters passed */ 


{ 
printf("Need to enter a public key name and SA key\n"); 
return 1; 


} 


name[0] = 0; /* Make copy of name parameters */ 
strcpy(name,argv[1]); 

memset(SAname, ' ', 64);  /* Make copy of Share Admin key name */ 
memcpy (SAname, argv[2] ,strlen(argv[2])); 


fp = fopen(name,"rb"); /* Open the file containing the token x/ 
if (!fp) 
{ 
printf("File %s not found.\n",argv[1]); 
return 1; 
} 
memset (token,0,2500) ; /* Read the token from the file x/ 
count = fread(token,1,2500, fp); 
fclose(fp); 
/* Determine length of token from length */ 
/* bytes at offset 2 and 3. */ 
token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in */ 
{ 
printf("Incomplete token in file\n"); 
return 1; 


} 


[RRR KER A KKK AK KK AK KAKA KKK KKK KKK KAKA KKK KEKE RARER KK | 


/* Find the certificate offset in the token */ 
/* x/ 
/* The layout of the token is x/ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* */ 


[ERK KER AKER A KKK A KEIR KEK KKK KKK KKK AKI KKK AK KEK AKER AKER | 


pub_sec_len = ((256 * token[10]) + token[11]); 
offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section */ 
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/* length from the length bytes at 

/* offset 2 of the section. 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 
tempOffset = offset + 4; /* Set offset to first subsection 


/* Parse each subsection of the certificate until the */ 
/* signature subsection is found or the end is reached.*/ 
/* (Identifier for signature subsection is Hex 45.) x/ 


while(token[tempOffset] != 0x45 && 
tempOffset < offset + cert_sec_len) 


tempOffset += 256 * token[tempOffset + 2] + token[tempOffset+3] ; 


| a ee ee eer «/ 
/* Check if no signature was found before the end of */ 
/* the certificate section. x/ 
Jxsezseseseceass tessessecocseedese sso aes —S> eee eeeeee */ 
if (token[tempOffset] != 0x45) 
{ 
printf("Invalid certificate\n"); 
return 1; 
} 


[KERR KER KK KEI K ERIK RRA K KEK KK EAR KEK IKKE IKKE IKKE AKER | 
/* Replace Private key name in certificate with the */ 
/* Share admin key name (expressed in ASCII). x/ 
[KERR KER A KKK KKK A KKK KKK KKK KKK AKER A KKK IKKE AKER ERK | 
text_length = tempOffset - offset + 70; 

memcpy (SAnameASCII,SAname, 64) ; 


Rresexeetiesees sessed =ooesessoce=enaes=assee-essaeo= «/ 
/* Convert the Share Admin key name to ASCII */ 
0 a eee ee ee ee «/ 
QDCXLATE(xlate_length, SAnameASCII, "QASCII "S "Qsys ab 


memcpy (&token[tempOffset + 6], SAnameASCII, 64); 


[RK RK ERA K RRA KKK KK KKK KKK KK EA KKK KKK A KKK A KKK KIKI KKK AKER KKK | 
/* Hash the certificate */ 
[KERR KER AKER IKEA KK AK KEK KK EAR KEK KKK IKEA AKA K KEKE AKER KKK | 
memcpy ((void*)rule_array,"SHA-1 ",8); 

rule_array_count = 1; 

chaining_vector_length = 128; 

hash_length = 20; 


CSNBOWH( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&text_length, 
&token[offset], 
&chaining_vector_length, 
chaining_vector, 
&hash_length, 
hash) ; 


if (return_code != 0) 


printf("One_Way_Hash Failed : return reason %d/%d\n", 
return_code, reason_code); 
return 1; 


} 


[BERR KER KKK AKER IKK A KKK KK AKER AKER IKEA AKA KKK KEK KER KKK | 


/* Create a signature x/ 
[RRR KER A KKK KEK K KKK KKK KK EAR KKK KKK IKKE AKA KKK KKK ERA K ERA KKK | 
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memcpy ((void*)rule_array, "ISO-9796",8) ; 
rule_array_count = 1; 


CSNDDSG( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&SAname_length, 

SAname, 

&hash_length, 

hash, 
&signature_length, 
&signature_bit_length, 
&token[tempOffset+70]); 


if (return_code != Q) 
{ 
printf("Digital Signature Generate Failed : return reason %d/%d\n", 
return_code, reason_code); 


return 1; 

} 
| Rana wieseresaseateeceeeeesa=ee=soesesecseseess=xe */ 
/* Check if the new signature is longer than the */ 
/* original signature x/ 
| ee ee ee eee */ 


if((token[tempOffset + 2] * 256 + token[tempOffset + 3]) - 70 != 
signature_length) 
{ 
printf("Signature Length change from %d to %d.\n", 
token[tempOffset + 2] * 256 + token[tempOffset + 3] - 70, 
signature_length) ; 


/* Adjust length in signature subsection */ 
token[tempOffset + 2] = signature_length >> 8; 
token[tempOffset + 3] = signature_length; 


/* Adjust length in certificate section */ 
token[offset + 2] (text_length + signature_length) >> 8; 
token[offset + 3] text_length + signature_length; 


/* Adjust length in token header section */ 

tempLength = 8 + pub_sec_len + 68 + text_length + 
signature_length; 

token[2] = tempLength >> 8; 

token[3] = tempLength; 

} 

else tempLength = token[2] * 256 + token[3]; 


[BRK R KK ERK KEKE A KK A KKK A KEE AKER AKER EKER | 


/* Write certified public key out to a file */ 


[RR KKK KERR KEK K KER AK KEIR KKK KEK KKK KK ER KKK | 


strcat(name,".CRT") ; /* Append .CRP to filename */ 
fp = fopen(name, "wb"); /* Open the certificate file */ 
if (!fp) 
{ 
printf("File open failed for output\n"); 
else 
{ 
fwrite(token, 1, tempLength, fp); 
fclose(fp); 
printf("Public token written to file %s.\n",name) ; 
} 
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Example: ILE RPG program for certifying a public key token 
Change this program example to suit your needs for certifying a public key token. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 
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Dx 
DR 
Dx 
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Dx 
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Dx« 
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Dx« 
DR 
Dx 
DT 
Dx 
DT 
DT 


KKKKKKEKK KKK KEKE KERR KEK KEK KR KKK KKK KKK KKK KKK KKK KKK KK KERR KRRERERER 


CERTKEY 


Sample program to certify a CCA public key certificate to be 
used for master key cloning. 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These example has not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these programs. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: FILENAME - File containing public key token 
RETAINED_KEY_NAME - Name of key to certify token 


Example: 
CALL PGM(CERTKEY) PARM(MYKEY.PUB CERTKEY) 


Use these commands to compile this program on iSeries: 

CRTRPGMOD MODULE(CERTKEY) SRCFILE(SAMPLE) 

CRTPGM PGM(CERTKEY) MODULE (CERTKEY) 
BNDDIR(QCCA/QC6BNDDIR) 


Note: Authority to the CSNDDSG and CSNBOWH service programs 
in the QCCA library is assumed. 


The Common Cryptographic Architecture (CCA) verbs used are 
Digital Signature Generate (CSNDDSG) and One _Way_Hash (CSNBOWH). 
KKKKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KEKE KKK KKK KKK KKK KKK KEREKKEEEKRE 
Declare variables used by CCA SAPI calls 
** Return code 
ETURNCODE S 9B 0 
** Reason code 
EASONCODE S 9B 0 
** Exit data length 
XITDATALEN S 9B 0 
«x Exit data 
XITDATA S 4 
** Rule array count 
ULEARRAYCNT S 9B 0 
** Rule array 
ULEARRAY S 16 
** Token length 
OKENLEN S 9B 0 INZ(2500) 
** Token and array for subscripting token 
OKEN DS 2500 
OKENARRAY 1 DIM(2500) 
iSeries: Cryptographic hardware 


Dx ** Chaining vector length 

DCHAINVCTLEN S 9B 0 INZ(128) 

Dx ** Chaining vector 

DCHAINVCT S 128 

Dx ** Hash length 

DHASHLEN S 9B 0 INZ(20) 

Dx ** Hash 

DHASH S 20 

Dx ** Text length 

DTXTLENGTH S 9B 0 

D* ** Signature length 

DSIGLENGTH S 9B © INZ(256) 

Dx ** Signature length in bits 

DSIGBITLEN S 9B 0 

De ee ee ee ee 
D* Declare variables for working with tokens 
DxeeeseesreeeesSeh eee ees seee Sec ee see eee eee eee oeet oc eeee eae 
Dx ** NAMEPTR and NAME are used for copying 
Dx *k private key name 

DNAMEPTR S * 

DNAME S 64 BASED (NAMEPTR) 

Dx xx Share administrator (certifying key) name length 
DSANAMELEN S 9B 0 

Dx xx Share administrator (certifying key) name 
DSANAME S 64 

D* ** Share administrator name expressed in ASCII 
DSANAMEASC S 64 

Dx xx Certificate section length 

DCRTSECLEN S 9B 0 

Dx ** Public key section length 

DPUBSECLEN S 9B 0 

Dx ** Index into PKA key token 

DTKNINDEX S 9B 0 

Dx ** Index into PKA key token 

DTMPINDEX S 9B 0 

Dx ** Structure used for aligning 2 bytes into a 
Dx xx 2 byte integer. 

DLENSTRUCT DS 2 

DMSB 1 i} 

DLSB 2 2 

DLENGTH 1 2B 0 

Dx ** File descriptor 

DFILED S 9B 0 

Dx ** File path and path length 

DPATH S 80 INZ(*ALLX'00') 
DPATHLEN S 9B 0 

D* ** Open flag - Create on open, open for writing, 
Dx ** and clear if exists 
DOFLAGW S 101 0 INZ(X'4A') 

Dx ** Open Flag - Open for Read only 

DOFLAGR S 101 0 INZ(1) 

D* ** Declares for calling QDCXLATE API 
DXTABLE S 10 INZ('QASCII ') 
DLIB S 10 INZ('QSYS ') 
DXLATLEN S 5 © INZ(64) 

D 

Dx 


DA KRKKK KKK KKK KKK KEK ERK KK ERK KKK KKK KKK KEK KERR KKK REE RK RRR KK RRR 


D* Prototype for Digital _Signature Generate (CSNDDSG) 


DA KRKKKKKKK KK KEK KKK ERK KEKE RRR KEKE KK KERR RK E RRR RR RER RK RR KEKE REE 


DCSNDDSG PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
DRARRYCT 9B 0 
DRARRY 16 
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DKEYIDLEN 9B 0 


DKEYID 2500 OPTIONS (*VARSIZE) 
DHSHL 9B 0 

DHSH 20 OPTIONS (*VARSIZE) 
DSIGFLDL 9B 0 

DSIGBTL 9B 0 

DSIGFLD 256 OPTIONS (*VARSIZE) 
Dx« 


DAK RAKKKK KKK KEK KK KEK KKK ERK KKK ERK KKK KEK KKK KKK KER KEK REE KK RRRREEK 


D* Prototype for One _Way Hash (CSNBOWH) 


DAR RRKKKKK KKK ERK KKK KKK KER KKK KR KK KK RRR KERR KK KR ERR KR ER KK RRERREKEK 


DCSNBOWH PR 

DRETCOD 9B 0 
DRSNCOD 9B 0 
DEXTDTALN 9B 0 
DEXTDT 4 
DRARRYCT 9B 0 
DRARRY 16 
DTXTLEN 9B 0 
DTXT 500 OPTIONS (*VARSIZE) 
DCHNVCTLEN 9B 0 
DCHNVCT 128 
DHSHLEN 9B 0 
DHSH 20 

Dx 

Dx« 


DA KRKKKKKKK KK ERK KEKE KKK KERR KERR RRR RRR RRR RRR KR ERR RRR KER EERE 
Dx Prototype for open() 

DAK RRK KKK KKK KER KK KEK KKK ERK KKK ERK KK R EKER KERR KR ER KEK RRR KEKE 
Dx value returned = file descriptor (OK), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B 0 VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U @ VALUE OPTIONS (*NOPASS) 
Dx« 


DAKAR KKKKKKK KEK KKK KERR KERR KERR RR KKK E RE KRR RK RRR ERK REE RRR RRR KR ERR RR ERKERRERR 
Dx Prototype for read() 

DA KRRKKKKK KK KER KK KEK KKK ERK KKK KERR RRR RK KERR KEK KR ERR RKR KK KERR 

Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
D« File descriptor returned from open() 

D 9B @ VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be read 

D 9B 0 VALUE 

Dx« 


DA RRR KKKKK KK KEK KKK KEK K KKK KEK KERR KEK KKK KERR ERK RRR RR KERR RK RRR RRR KER KERR RER KERR 


D* Prototype for write() 


DA KRKKKKKKK KK ERK KEKE KKK KERR KKK RRR KERR REE RE KERR REE KERR ER KEK RRERERK 
D« value returned = number of bytes written, or -1 


Dwrite PR 9B 0 EXTPROC('write') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

D* Output buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be written 

D 9B 0 VALUE 

Dx« 


DAKAR KKKKKKK KK ERK KK KEK K KKK KEKE RR KEK RR E RE KR R RE KERR RR KER RE RRR RRR KR ERR KER ERERERE 


D* Prototype for close() 


DARK RKKKKK KK KEK KKK KEK KKK RRR KK RRR KKK KER KEKE RK RRR RR KK ERK RRR RK KK ER KERR RRKR KERR 


230 = iSeries: Cryptographic hardware 


Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

D« File descriptor returned from open() 

D 9B 0 VALUE 

Dx« 
ee eee ee ee ee 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 
DkeesseecesosSceecusctessssecSsscecesecscssesscses Sse ceeSesceece 
DMSG 5 75 DIM(7) CTDATA PERRCD(1) 
DMSGLENGTH S 9B © INZ(75) 

D DS 

DMSGTEXT 1 75 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' t) 

DMSGTYPE S 10 INZ('*INFO i, 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B © INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx* 

CR KKK KK KKK KKK KEKE KR EKER KER ERK KK EKER KKK EK RRR EKER RRR ERE RE RK ERR 
Cx START OF PROGRAM * 
CK KKK KKK KKK KKK KR KR EK KEK KEK ERK KK KK ERK KR EK KKK EKER KERR ER ERE RK ERR ERE 
C *ENTRY PLIST 

C PARM FILEPARM 32 
C PARM CKEY 32 


CK KKK KKK KKK KEKE KR ERE KK EK ERK KK EKER KKK RK KKK ER ERK RR ER ERE RK ERR ERE 


Cx Open certificate file 
CR K KKK KKK KKK KK KKK KR EKER KER ER KERR EKER KKK EKER ER ERR RR ERE RK REKERREERE 


Cx Ce ee * 

Cx  »** Build path name * 

Cx Pe see weet eee see eeeeee * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx Pie eeee eee se eee eee * 

Cx »* Open the file * 

Cx ee * 

C EVAL FILED = open(PATH: OFLAGR) 
Cx Pishessesseeesaesesesos * 

Cx »* Check if open worked * 

Cx Peeeeeeese eset see eeeees * 

C FILED IFEQ -1 

Cx FieeeSeee coos ee cee see ee see eee seo see * 

Cx * Open failed, send an error message * 

Cx Aico sees e Ste ee Se eee alee * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx 

C ENDIF 

Ce NoeesiasaSscsecescolessecss sso Sssssoseoseossosssce * 
Cx * Open worked, read certificate and close the file * 
Cx (aos mecsecs eee ses ose secs ete se cee eee eee sees * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx* 

Cx Koosoceeeccestee csc saceSseesesocee eS * 

Cx * Check if read operation was OK * 

Cx ee ee eee ee) * 

C TOKENLEN IFEQ -1 

C MOVEL MSG (2) MSGTEXT 
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Cx 


EXSR SNDMSG 
ENDIF 
Kee eee eee ee ee * 
* Check if certificate length is valid * 
Kee eee eee ee * 
EVAL MSB = TOKENARRAY (3) 
EVAL LSB = TOKENARRAY (4) 
LENGTH IFLT TOKENLEN 
Kee ee - - -  - - * 
* Certificate length is not valid * 
Keen eee -  - - * 
MOVEL MSG (3) MSGTEXT 
EXSR SNDMSG 
RETURN 
ENDIF 


CR KKK KK KEKE KKK KKK KKK EKER KER ERE RRR KER KERR EKER RE RE RE RR ERE RRR ERREERE 
Find the certificate in the token 


Cx« 
Cx« 
C* 
Cx 
Cx« 
Cx 
Cx« 
Cx* 
Cx 


The layout of the token is 


Token header - 8 bytes - including 2 length bytes 
Public key section - length bytes at offset 2 
Private key name - 68 bytes 

Certificate section 


CR KKK KKK KKK KK EK KEK RK KEK KKK ERE KK EKER KEK RRR ERR ERE RK ER ERE REE ERR ERE 


Cx« 
Cx« 
Cx 


Cx« 


Kee eee eee * 
* Certificate starts after the public key header section * 
Kee eee ee ee a a * 
EVAL MSB = TOKENARRAY (11) 
EVAL LSB = TOKENARRAY (12) 
EVAL PUBSECLEN = LENGTH 
EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Kee ee * 
* Determine length of certificate section * 
Kee eee * 
EVAL MSB = TOKENARRAY(TKNINDEX + 2) 
EVAL LSB = TOKENARRAY(TKNINDEX + 3) 
EVAL CRTSECLEN = LENGTH 
EVAL TMPINDEX = TKNINDEX + 4 
Kee eee ee ee * 


+ 


Parse each subsection of the certificate until the * 
signature subsection is found or the end is reached.* 
(Identifier for signature subsection is Hex 45.) * 


+ 


Kee eee ee ee nn a * 
DOW (TOKENARRAY (TMPINDEX) <> X'45') AND 
(TMPINDEX < TKNINDEX + CRTSECLEN) 
EVAL MSB = TOKENARRAY(TMPINDEX + 2) 
EVAL LSB = TOKENARRAY(TMPINDEX + 3) 
TMP INDEX ADD LENGTH TMP INDEX 
ENDDO 
Kee eee -  - - * 
* Check if no signature was found before the end of * 
* the certificate section. * 
Kee eee ee ee a * 
IF TOKENARRAY (TMPINDEX) <> X'45' 
MOVEL MSG(4) MSGTEXT 
EXSR SNDMSG 
RETURN 
ENDIF 


CR KKK KKK KKK KK KEKE KKK KEK KKK ERE RK EKER KEK KEK KERR EKER KERR ERE REE KERR ERE 
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Cx Sign the Certificate 


CR KKK KK KK KKK KK KKK KR EKER KER ER KKK EKER KER KERR ER ER ERK RR EKER ERE RRR 


Cx* He se st mt i a ce a is a ce a ice * 
Cx * Convert the Certifying Keyname to ASCII * 
Cx« ¢ sae Seeee secsce meses seas eee eee = a ees Sos Sees seaaseeese * 
C EVAL SANAMELEN = %LEN(%TRIM(CKEY) ) 
C SANAMELEN SUBST CKEY:1 SANAME 

C MOVEL SANAME SANAMEASC 

C CALL "QDCXLATE' 

C PARM XLATLEN 

C PARM SANAMEASC 

C PARM XTABLE 

C PARM LIB 

Cx« neice wessacsacueSSecan seetoosessescoscsceseeeecsecsce * 
Cx * Replace the private key name in the certificate * 
Cx* Te i si a sc a a tc ee * 
C EVAL NAMEPTR = %ADDR(TOKENARRAY (TMPINDEX + 6)) 
C MOVEL SANAMEASC NAME 

Cx« Saeaactwosoacuaseesseeseceascasensesenseceseeeeceosece * 
Cx * Calculate length of data to hash * 
Cx * TKNINDEX is the start of the certificate, * 
Cx * TMPINDEX is start of signature subsection, * 
Cx * signature subsection header is 70 bytes long * 
Cx« PmeaseweteaceeeceSscecoeseaecaecuscessaaces cee asesees * 
C EVAL TXTLENGTH = TMPINDEX - TKNINDEX + 70 
Cx* Te eh a ac i el a * 

Cx * Set the keywords in the rule array * 

Cx« stesnsenesesense See eeeeeeseeesseoseekeceeS * 

C MOVEL "SHA-1 RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 

C* es a ot a a ws nl * 

Cx * Call One Way Hash SAPI * 

Cx« seeencacssceseaceeceess=ee * 

C CALLP CSNBOWH (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT: 

C RULEARRAY : 

C TXTLENGTH: 

C TOKENARRAY (TKNINDEX) : 
C CHAINVCTLEN: 

C CHAINVCT: 

C HASHLEN: 

C HASH) 

Cx ‘#eeeeettesescceecetsse ace * 

Cx »* Check the return code * 

Cx. kxeSesessesosoossosssaese= * 

¢ RETURNCODE IFGT 0 

Cx* casas na noone Seon ooees * 

Cx * Send failure message * 

Cx« tia coves soceaceseeceenes * 

C MOVEL MSG(5) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNBOWH' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx* Cals scSee anon ama eee eee meee oe * 

Cx * Set the keywords in the rule array * 

Cx« {wesaovohaacaccasececes Seseeesetecsocscces] * 

C MOVEL 'TS0-9796' RULEARRAY 

¢ Z-ADD 1 RULEARRAYCNT 

Cx* ea a a ee cae ms te mse eee * 

Cx * Adjust TMPINDEX to where signature starts* 

Cx * jn the certificate * 
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C TMP INDEX ADD 70 TMP INDEX 

Cx a i ep i a a al ep eae * 

Cx * Set the Key name length * 

Cx« Hesiees ooeceS se eseS se aSeseeees sees seSoseeeee * 

C Z-ADD 64 SANAMELEN 

Cx tcc cocoa casas Kno asa ace aoa oate * 

Cx * Call Digital Signature Generate SAPI * 

Cx« La caoasaccaasasesuenanasceaSealeeaoseees * 

C CALLP CSNDDSG (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT : 

C RULEARRAY : 

C SANAMELEN: 

C SANAME : 

C HASHLEN: 

C HASH: 

C SIGLENGTH: 

C SIGBITLEN: 

C TOKENARRAY (TMPINDEX) ) 
(Cx. #eSssSSsecoseosossesoeaee * 

Cx * Check the return code * 

(ee ee ee ee * 

C RETURNCODE IFGT 0 

Cx acckoce cas ceae eee eee * 

Cx * Send failure message * 

Cx« tecsasacseaces ooheesseae * 

C MOVEL MSG(5) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSNDDSG' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx 

(Ck SaeeSeaSseseessesoaa aaa a aa eee a Se Se eee ae * 

Cx »* Check if the new signature is longer than the * 

Cx »* original signature * 

Ck eS se heceees assess seese se Spe cece See eee ee ees * 

Cx «x Adjust TMPINDEX back the start of the subsection 

C TMP INDEX SUB 70 TMP INDEX 

Cx ** Get two byte length of subsection 

C EVAL MSB = TOKENARRAY(TMPINDEX + 2) 
C EVAL LSB = TOKENARRAY(TMPINDEX + 3) 
Cx ** Subtract length of subsection header 

C LENGTH SUB 70 LENGTH 

Cx ** Compare old length with new length 

C LENGTH IFNE SIGLENGTH 

Cx* i i lal th ects, * 

Cx * Adjust certificate lengths * 

Cx« eas eecee sessseeeceeseaaseceece=ees * 

Cx ** Adjust signature length 

C EVAL LENGTH = SIGLENGTH 

C EVAL TOKENARRAY (TMPINDEX + 2) = MSB 
C EVAL TOKENARRAY (TMPINDEX + 3) = LSB 
Cx «x Adjust certificate section length 

C EVAL LENGTH = LENGTH + TXTLENGTH 

C EVAL TOKENARRAY (TKNINDEX + 2) = MSB 
C EVAL TOKENARRAY (TKNINDEX + 3) = LSB 
Cx *x Adjust length in token header section 

C EVAL LENGTH = LENGTH + 8 + PUBSECLEN + 68 
C EVAL TOKENARRAY (3) = MSB 

C EVAL TOKENARRAY (4) = LSB 

C Z-ADD LENGTH TOKENLEN 

C ENDIF 
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Cx 

CRRA KK KEKE KKK KKK KR EKER KER ERK KK EKER KERR EKER ER ERR RR ERE RRR ERRERE 
Cx Write certified public key out to a file 

CK K KKK KKK KKK KK KKK KR EKER KER ER KEK KEK ERK RK EK RRR ER ERR RR ERE RRR ERR ERE 
Cx ** Build path name 


C EVAL %SUBST (PATH: PATHLEN+1:4) = '.CRT' 
Cx* 

Cx ** Open the file 

Cx« 

C EVAL FILED = open(PATH: OFLAGW) 

Cx 

Cx ** Check if open worked 

Cx* 

C FILED IFEQ -1 

Cx« 

Cx ** Open failed, send an error message 

Cx« 

C MOVEL MSG (6) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ELSE 

Cx 

Cx ** Open worked, write certificate out to file and close file 
Cx* 

C CALLP write (FILED: 

C TOKEN: 

C TOKENLEN) 

C CALLP close (FILED) 

Cx« 

Cx ** Send completion message 

Cx 

C MOVEL MSG(7) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 41: PATHLEN + 4) = 
C %SUBST(PATH: 1: PATHLEN + 4) 
C EXSR SNDMSG 

C ENDIF 

Cx* 

C SETON LR 


Cx« 
(III I III RII III RR ROR I III IO 


Cx Subroutine to send a message 
CR KKK KKK KKK KKK KKK RE KEK KKK ERK KK EKER KKK EKER KEKE RR RR ERE RE REK ERR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 


The input file could not be opened. 

There was an error reading from the file. 

The length of the certificate is not valid. 

The certificate is not valid. 

CSNBOWH failed with return/reason codes 9999/9999. 
The output file could not be opened. 

The certified token was written to file 
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Example: ILE C program for obtaining a master key share 
Change this program example to suit your needs for obtaining a master key share. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


fp Hosacesoustscsssssdsonsosseshessessessees seuecassessssssssescuesesas */ 
/* GETSHARE x/ 
/* x/ 
/* Sample program to obtain a master key share as part of the x/ 
/* master key cloning process. x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. */ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of */ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: Share number x/ 
/* Name of share sender private key x/ 
/* Name of certifying key */ 
/* Stream file containing receiver certificate x/ 
/* x/ 
/* x/ 
/* Example: */ 
/* CALL PGM(GETSHARE) PARM(2 SENDR SAKEY RECVR.PUB) x/ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is */ 
/* already identified either by defaulting to the CRPO1 x/ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verbs used is */ 
/* Master_Key Distribution (CSUAMKD). */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(GETSHARE) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(GETSHARE) =MODULE(GETSHARE) */ 
/* BNDDIR(QCCA/QC6BNDDIR) */ 
/* x/ 
/* Note: Authority to the CSUAMKD service program */ 
/* in the QCCA library is assumed. */ 
/* x/ 
pata ee = eases ses ees ase eee ae Seen ae eee ree Ss Soa ea eee aa */ 


#include <stdio.h> 
#include <string.h> 
#include "csucincl.h" 
#include "decimal.h" 


extern void QDCXLATE(decimal(5,0), char *, char*, char *); 
#pragma linkage (QDCXLATE, OS, nowiden) 


int main(int argc, char *argv[]) 
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long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 0; 
char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 

long cloneInfoKeyLength = 500; 
unsigned char cloneInfokey[500] ; 
long cloneInfoLength = 400; 
unsigned char cloneInfo[400]; 
long shareldx; 

char name[64] ; 

char SAname[64]; 


| eee ee ee eee eee oe eee eee */ 
/* Declares for working with a PKA token */ 
| ee eae er */ 
long pub_sec_len; /* Public section length x/ 
long prv_sec_len; /* Private section length x/ 
long cert_sec_len; /* Certificate section length */ 
long info_subsec_len; /* Information subsection length x/ 
long offset; /* Offset into token */ 
long tempOffset; /* (Another) Offset into token x/ 
long tempLength; /* Length variable */ 
long tempLenl, tempLen2; /* temporary length variables x/ 
char cloneShare[] = "cloneShareQQ"; /* Base cloning share filename */ 
long count; /* Number of bytes read in from file */ 


decimal(15,5) shareParm; /* Packed 15 5 var used for converting */ 
/* from packed 15 5 to binary. Numeric */ 
/* parms on iSeries are passed as dec 15 5*/ 
FILE «fp; /* File pointer x/ 


if (argc < 5) /* Check the number of parameters passed */ 


printf("Need to Share index, Sender name, SA name, and cert\n"); 
return 1; 


} 


/* Convert the packed decimal 15 5 parm */ 
/* to binary. */ 
memcpy (&shareParm, argv[1],sizeof(shareParm) ); 
shareIdx = shareParm; 
memset (name,' ',64); /* Copy the Private key name parm to a~ */ 
memcpy (name,argv[2],strlen(argv[2])); /* 64 byte space padded var. */ 
memset (SAname,' ',64); /* Copy the Share Admin name parm to a */ 
memcpy (SAname, argv[3],strlen(argv[3]));/* 64 byte space padded var. */ 


fp = fopen(argv[4],"rb"); /* Open the file containing the token x/ 


if (!fp) 
{ 
printf("File %s not found.\n",argv[4]); 
return 1; 
} 
memset (token,0,2500) ; /* Read the token from the file */ 


count = fread(token,1,2500, fp); 
fclose(fp); /* Close the file */ 


/* Determine length of token from length */ 
/* bytes at offset 2 and 3. */ 
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token_len = ((256 * token[2]) + token[3]); 
if (count < token_len) /* Check if whole token was read in 


printf("Incomplete token in file\n"); 
return 1; 


} 


[BERR KER AKER AKER IKKE AK KEK KKK KERIKERI KK AKKEA KIER K ERA KEE KK | 


/* Find the certificate offset in the token */ 
/* x/ 
/* The layout of the token is */ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* x/ 


[BRK RK ERA KKRAK ERIK KARR EK AREA AKER AK KK A KK E AKIRA A KEE | 


pub_sec_len = ((256 * token[10]) + token[11]); 


*/ 


offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section 

/* length from the length bytes at 

/* offset 2 of the section. 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 


[RRR KKK AKER AKER K KKK KKK KKK KKK KKK A KKK AK KEI KKK KKK AKER KKK | 
/* Obtain a share */ 
[KERR KER KKK A KKK KKK KKK KK AK KKK KKK AK KK AK KE AKI IKKE AKER KKK | 
memcpy((void*)rule_array,"OBTAIN ",8); /* Set rule array 
rule_array_count = 1; 


CSUAMKD( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&shareldx, 
name, 

SAname, 
&cert_sec_len, 
&token[offset], 
&cloneInfoKeyLength, 
cloneInfoKkey, 
&cloneInfoLength, 
cloneInfo); 


if (return_code != 0) 
{ 
printf("Master Key Distribution Failed : return reason %d/%d\n", 
return_code, reason_code); 


return 1; 
else 
[RRR KKK KKK AKER KKK AK KAKA K KKK IKK KIRA KK AK KAKA K ERA | 
/* Write signed token out to a file x/ 


[RR KKK KKK KER AKER KR AK KK AKK KA KKK IK IKK AK KR AK KEKK KIA KK ERIK ERK KE | 


printf("Master Key Distribution worked\n"); 


/* Build file path name 
if (shareIdx < 9) cloneShare[11] = '0' + shareldx; 
else 

{ 
cloneShare[10] 
cloneShare[11] 


"L's 
'Q@' + shareIdx - 10; 
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*/ 
*/ 
*/ 


*/ 


} 


fp = fopen(cloneShare,"wb"); /* Open the file */ 
if (!fp) 
{ 


printf("File %s not be opened for output.\n",cloneShare) ; 


return 1; 
} 
/* Write out the length of KEK x/ 
fwrite((char*) &cloneInfoKeyLength,1,4, fp); 
/* Write out the KEK x/ 
fwrite((char*)cloneInfoKey,1,cloneInfoKeyLength, fp) ; 
/* Write out the length of info */ 
fwrite((char*)&cloneInfoLength,1,4, fp); 
/* Write out the clone info x/ 


fwrite((char*)cloneInfo,1,cloneInfoLength, fp) ; 
printf("CLone share %d written to %s.\n",shareldx,cloneShare) ; 


fclose(fp); /* Close the file */ 
return 0; 
} 


Example: ILE RPG program for obtaining a master key share 
Change this program example to suit your needs for obtaining a master key share. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKKKK KERR KKK ER KKK KE RRR KERR KERR RR ERR KR ERR RRR KEKE REE EERE 
D* GETSHARE 

Dx« 

D* Sample program to obtain a master key share as part of the 
D* master key cloning process. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx« 

D* Parameters: Share number 

Dx Name of share sender private key 

Dx Name of certifying key 

Dx Path name of stream file containing receiver certificate 
Dx 

D* Example: 

D* CALL PGM(GETSHARE) PARM(2 SENDR SAKEY RECVR.PUB) 

Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(GETSHARE) SRCFILE(SAMPLE) 

D* CRTPGM PGM(GETSHARE) MODULE (GETSHARE) 

Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx 
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D* Note: Authority to the CSUAMKD service program 
Dx in the QCCA library is assumed. 


Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used is 
D* Master_Key Distribution (CSUAMKD). 


Dx 

DA RRKKKKKKK KK ERK KKK KKK KERR KR KERR KERR RRR RRR KR ERR RRR RRR RE RRERRRRRERER 
Dkscteseesesee ease eee eee eee ce eee ee cee ese See see eee eee es = 
D* Declare variables used by CCA SAPI calls 

Deteaea mea se Sas sesae SSeS se lS aaaoseoeSs SS aes SS aa = Se 
Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE Ss 9B 0 

Dx ** Exit data length 

DEXTTDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

D* ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

Dx ** Token and array for subscripting 
DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx ** Private key name 

DPRVNAME S 64 

Dx ** Certifying key name 

DCERTKEY S 64 

Dx« 

DLSTRUCT DS 

Dx ** Clone KEK length - one is binary form and the 
D* xx other is used for reading the value from a file 
DCLONEKEKL 9B 0 INZ(500) 

DCLONEKEKLC 1 4 

Dx ** Clone info length - one is binary form and the 
Dx ** other is used for reading the value from a file 
DCLONEINFOLEN 9B 0 INZ(400) 
DCLONEINFOLENC 5 8 

Dx ** Cloning key-encrypting-key 

DCLONEKEK S 500 

Dx ** Cloning info 

DCLONEINFO S 400 

D* ** Share index 

DSHAREIDX 5 9B 0 

Dx xx Data structure for aligning 2 bytes into 
Dx ** a2 bytes integer 

DLENSTRUCT DS 2 

DMSB 1 il 

DLSB 2 2 

DLENGTH 1 2B 0 

Dx ** Certificate section length 

DCRTSECLEN S 9B 0 

Dx ** Public key section length 

DPUBSECLEN 5 9B 0 

Dx ** Index into Token array 

DTKNINDEX S 9B 0 

Dx ** Number of bytes to write out to a file 
DOUTLEN S 9B 0 

Dx ** File descriptor 

DFILED S 9B 0 

Dx ** File path and length 

DPSTRUCT DS 

DPATH 80 INZ(*ALLX'00') 

DSIDX 11 12B 0 
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DPATHLEN S 9B 0 


D* ** Open Flag - Open for Read only 

DOFLAGR S 101 0 INZ(1) 

Dx ** Open flag - Create on open, open for writing, 
Dx Kk and clear if exists 

DOFLAGW S 101 © INZ(X'4A') 

Dx ** Base name of file to store cloning share 
DSHAREFILE S 12 INZ('cloneShared0') 

Dx« 


DA RRKKKKK KK KKK KKK KERR KK RRR KKK KKK KER KEK KKK KKK KERR KERR KKK KERR 


D* Prototype for Master_Key Distribution (CSUAMKD) 


DA KRAK KKK KKK KEK KK KERR KK E RRR ERR KK KERR RRR RK KR RRR RK RER EKER ERR 


DCSUAMKD PR 

DRETCOD 9B 0 

DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DSHRINDX 9B 0 

DKYNAM 64 

DCRTKYNAM 64 

DCRTL 9B 0 

DCRT 2500 OPTIONS (*VARSIZE) 
DCLNKEKL 9B 0 

DCLNKEK 1200 OPTIONS (*VARSIZE) 
DCLNL 9B 0 

DCLN 400 OPTIONS (*VARSIZE) 
Dx« 


DAK RKKKKKK KKK KKK KK ERK KK ERK KKK KKK KKK KEK KKK KKK KER KEKE KKK REE EK 


D* Prototype for open() 


DA KRKKKKKKK KKK KKK KER KEK KERR KERR KERR KER KERR ER KEK RR ER RK RR EKER ERE 
Dx value returned = file descriptor (0K), -1 (error) 


Dopen PR 9B 0 EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B 0 VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx 


DARK KKKKKKK KER KKK KEK KKK KKK KKK KKK KER KK RRR KKK KERR KK ERK KERR RK KR ER KEK RRERKE RRR 


D* Prototype for write() 


DA KRK KKK KKK KKK KKK KEK KK RRR RRR ERR KK RRR KEKE R KEK RR ER KEKE KEKE REE 
D« value returned = number of bytes written, or -1 


Dwrite PR 9B 0 EXTPROC('write') 
D« File descriptor returned from open() 

D 9B 0 VALUE 

Dx Output buffer 

D 2500 OPTIONS (*VARSIZE) 
Dx Length of data to be written 

D 9B 0 VALUE 

Dx 


DAK RKKKKKKK KKK KKK KEK KKK RR KKK KKK KK ER KK KERR RRR KER KR ERK RRR KR KKK ER EK RRERKE KERR 


Dx Prototype for read() 


DAK RKKKKKK KK KKK KKK ERK KK ERK KKK KKK KK R KEK KEKE KKK KER RK KERR RK ERKEER 
Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
D* Length of data to be read 

D 9B 0 VALUE 

Dx 
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DA KKRK KKK KKK KER KKK KEK KKK KKK KK RRR RRR KKK KER K RRR RR KK RRR KKK KEKE KK ERE RR RRR KR ER 
D* Prototype for close() 

DA KRKK KKK KKK KEKE KKK KKK KERR KERR KEK RRR RR RRR KEKE RRR KER RE RRR RRR RRR RE RERERERE 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx 

Peace SSesseosseseccosseaseSsceseceesceseeseeSse soe cesseecescess 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

a ee 
DMSG S 75 DIM(6) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(80) 

D DS 

DMSGTEXT 1 80 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ms) 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' 5) 

DMSGTYPE S 10 INZ('*INFO ") 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B © INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(O) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CX KKK KKK KKK KK KKK KR KK ERK KEK ERE KKK KERR KEKE KR ERE RK RR ERE RRR EKER 
Cx START OF PROGRAM * 
Cx * 
Cc *ENTRY PLIST 

C PARM SINDEX 15 5 
C PARM PRVKEY 32 
C PARM SAKEY 32 
C PARM FILEPARM 32 


CRRA KKK KKK KK KKK KR KK ERK EK ERE KK EKER KERR EKER EKER KERR ERE RE RK ERR ERE 


Cx Open certificate file 
CR K KK KKK KKK KKK KKK EKER KER ERE KKK KEK KERR EKER ER ERR RR ERE RRR ERREERE 


Cx Fesseseeebeeseeeceees= * 

Cx  »** Build path name * 

Cx feseme seen eee see eee eee * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 
C PATHLEN SUBST FILEPARM: 1 PATH 

Cx Posse ce see came eee emia — * 

Cx »* Open the file * 

Cx* (ossaecseeosesceoeses= * 

C EVAL FILED = open(PATH: OFLAGR) 
Cx Pace caee aime meee eminem ae * 

Cx  »* Check if open worked * 

Cx« Lecseeeseeocseanecaeces * 

C FILED IFEQ -1 

Cx* Pace eka scot ene hee e cee ees See cme * 

Cx * Open failed, send an error message * 

Cx« cane aes eeees Sete se Seeeseeeeeseoesscas * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx 

C ENDIF 

Cx NesSsssslsseeeeseesesecssceeossessosscsesoesesse * 
Cx * Open worked, read certificate and close file * 
Cx We cSe see see te eee seca seee ee eeSSese eee seec ee * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx* 
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Cx« 


Kee ----- * 

* Check if read operation was OK * 

Keene eee - - - - -  - * 

TOKENLEN IFEQ -1 

MOVEL MSG(2) MSGTEXT 
EXSR SNDMSG 
ENDIF 

Kee ----- * 


* Check if certificate length is valid * 
* The length bytes start at position 3 * 


Kee ee * 
EVAL MSB = TOKENARRAY (3) 
EVAL LSB = TOKENARRAY (4) 
LENGTH IFLT TOKENLEN 
Kee eee * 
* Certificate length is not valid * 
Keene eee * 
MOVEL MSG (3) MSGTEXT 
EXSR SNDMSG 
RETURN 
ENDIF 


CK KKK KEKE KK KKK KKK KEE KEK KKK ERK KK EKER KKK RK KKK EKER KERR ERE RE RK ERR ERE 


Cx* 
Cx* 
Cx* 
Cx« 
Cx« 
Cx 
Cx 
C* 
Cx 
Cx« 


Find the certificate in the token 

The layout of the token is 

- Token header - 8 bytes - including 2 length bytes 

- Public key section - length bytes at position 3 (11 overall) 
- Private key name - 68 bytes 

- Certificate section 


Note: 1 is added because RPG arrays start at 1. 


CR KKK KK KK KKK KKK KKK KEKE RK ER ER KEK KKK ERK RRR KERR EKER ERR ER ERR ERE REE 


Cx* 


EVAL MSB = TOKENARRAY (11) 

EVAL LSB = TOKENARRAY (12) 

EVAL PUBSECLEN = LENGTH 

EVAL TKNINDEX = PUBSECLEN + 68 + 8+ 1 
Keene ee ee ee * 


* Determine length of certificate section * 
* Length bytes are at position 2 of the * 


* section. 

Keene ee ee ee * 
EVAL MSB = TOKENARRAY(TKNINDEX + 2) 
EVAL LSB = TOKENARRAY(TKNINDEX + 3) 
EVAL CRTSECLEN = LENGTH 


CR KKK KK KKK KKK KEKE KR EKER KER ERE KK RK ERK KR EK EER EKER RR ERE REE ERR 


Cx* 


Obtain a certificate 


CR KKK KKK KKK KK KKK KEKE KE KK EK ERK KK EKER KKK RK KKK EKER KERR ERE RE RK ERR ERE 


Cx« 
Cx* 
Cx* 
Cx« 
C 
Cx 
C* 
Cx* 
C 
C 
Cx« 
Cx* 
Cx* 
C 
C 


Kee eee ee * 
* Set share index number * 
* (Convert from packed 15 5 to binary) * 
Kee eee ee * 
Z-ADD SINDEX SHAREIDX 
Kee eee ee * 
* Set private key name * 
Kee ee ee ee ee * 
EVAL LENGTH = %LEN(%TRIM(PRVKEY) ) 
LENGTH SUBST PRVKEY:1 PRVNAME 
Kee ee ee * 
* Set certifying key name * 
Kee ee ee ee ee * 
EVAL LENGTH = %LEN(%TRIM(SAKEY) ) 
LENGTH SUBST SAKEY:1 CERTKEY 
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Cx Wessssssssssscesscssscccsssseseeseeescsecsce * 

Cx »* Set the keywords in the rule array * 

Cx a ee ee * 

C MOVEL ‘OBTAIN ' RULEARRAY 

C Z-ADD 1 RULEARRAYCNT 
Cx« LIocaascscesseeweccsescsceoesaecascsose * 

Cx »* Call Master Key Distribution SAPI * 

Cx I i a a i oi acl ey * 

C CALLP CSUAMKD (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 

C RULEARRAYCNT: 
C RULEARRAY : 

C SHAREIDX: 

C PRVNAME : 

C CERTKEY: 

C CRTSECLEN: 

C TOKENARRAY (TKNINDEX) : 
C CLONEKEKL: 

C CLONEKEK: 

C CLONEINFOLEN: 
C CLONEINFO) 
Geo BWesesScesscssssosseasesse * 

Cx * Check the return code * 

Ck Fess reseeseseseeeceesecen * 

C RETURNCODE IFGT 0 

Cx* tevesceeseeseeecea= sees * 

Cx * Send failure message * 

Cx« teens cneceSseeeeeseseess * 

¢ MOVEL MSG(4) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C MOVEL "CSUAMKD' SAPI 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx« 


CR R KKK KKK KKK KK KEKE KR KK ERK KEK ERE KKK KER KEK KEK KERR ERE RK RR ERE RE RK EKRERE 


Cx Write share out to a file 
CR K KKK KKK KKK KK KEKE KKK KER KER ERE RRR KEKE RR ER ERR ERE RR RR ERE REE ERR 


Cx ** Build path name 


C MOVEL *ALLX'00' PATH 

C MOVEL SHAREFILE PATH 

C SIDX ADD SHAREIDX SIDX 

¢ SHAREIDX IFGE 10 

C SIDX ADD 246 SIDX 

C ENDIF 

Cx* 

Cx *x Open the file 

Cx 

C EVAL FILED = open(PATH: OFLAGW) 
Cx« 

Cx ** Check if open worked 

Cx* 

C FILED IFEQ -1 

Cx 

Cx ** Open failed, send an error message 

Cx 

C MOVEL MSG(5) MSGTEXT 
C EXSR SNDMSG 

Cx« 

C ELSE 

Cx* 

Cx ** Open worked, write certificate out to file and close file 
Cx« 

C Z-ADD 4 OUTLEN 
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C CALLP write (FILED: 

C CLONEKEKLC: 

C OUTLEN) 

C CALLP write (FILED: 

C CLONEKEK: 

C CLONEKEKL) 

C CALLP write (FILED: 

C CLONEINFOLENC: 
C OUTLEN) 

C CALLP write (FILED: 

C CLONEINFO: 

C CLONEINFOLEN) 
C CALLP close (FILED) 

Cx« 

Cx ** Send completion message 

Cx* 

C MOVEL MSG (6) MSGTEXT 

C EVAL %SUBST(MSGTEXT: 32: 12) = 

C %SUBST(PATH: 1: 12) 
C EXSR SNDMSG 

C ENDIF 

Cx* 

C SETON LR 
Cx« 


CK KKK KKK EK KKK EKER RE RE KK KEK ERK KK EKER KKK RK EK KEK ERK RR ERE RRR ERRERE 


Cx Subroutine to send a message 
CR KKK KK KKK KKK KEKE KR EKER KER ER KKK RK ERK RR EK REE REK ERR RR EKER KERR REE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

Cx* 


** 

The input file could not be opened. 

There was an error reading from the file. 

The length of the certificate is not valid. 
CSUAMKD failed with return/reason codes 9999/9999. 
The output file could not be opened. 

The share was written to file 


Example: ILE C program for installing a master key share 
Change this program example to suit your needs for installing a master key share. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


[dre seeese aes ee eoseceeaes eee Scere sees eeeeeseceseeeee see skeeeeeessens */ 
/* PUTSHARE x/ 
/* x/ 
/* Sample program to install a master key share as part of the x/ 
/* master key cloning process. x/ 
/* */ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999, 1999 */ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function x/ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF */ 
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/* 


/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
/* these programs and files. 

/* 

/* 

/* Note: Input format is more fully described in Chapter 2 of 
/* IBM 4758 CCA Basic Services Reference and Guide 

/* (SC31-8609) publication. 

/* 

/* Parameters: Share number 

/* Name of share receiver private key 

/* Name of certifying key 

/* Stream file containing sender certificate 

/* 

/* 

/* Example: 

/* CALL PGM(PUTSHARE) PARM(2 RECVR SAKEY SNDR.PUB) 

/* 

/* 

/* Note: This program assumes the card with the profile is 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


/* already identified either by defaulting to the CRPO1 
/* device or by being explicitly named using the 

/* Cryptographic_Resource_ Allocate verb. Also this 

/* device must be varied on and you must be authorized 
/* to use this device description. 

/* 

/* The Common Cryptographic Architecture (CCA) verbs used is 
/* Master_Key Distribution (CSUAMKD) . 

/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


#i 
#i 
#i 
#i 


Use these commands to compile this program on iSeries: 

ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(PUTSHARE) SRCFILE(SAMPLE) 

CRTPGM PGM(PUTSHARE) MODULE (PUTSHARE) 
BNDDIR(QCCA/QC6BNDDIR) 


Note: Authority to the CSUAMKD service program 
in the QCCA library is assumed. 


nclude <stdio.h> 
nclude <string.h> 
nclude "csucincl.h" 
nclude "decimal .h" 


extern void QDCXLATE(decimal(5,0), char *, char*, char *); 
#pragma linkage (QDCXLATE, OS, nowiden) 


int main(int argc, char *argv[]) 


| ee ee ee ee ee 
long return_code = Q; 

long reason_code = Q; 

long exit_data_length = 0; 

char exit_data[4]; 

char rule_array[24]; 

long rule_array_count; 

long token_len = 2500; 

char token[2500]; 

long cloneInfoKeyLength = 500; 
unsigned char cloneInfokey[500] ; 
long cloneInfoLength = 400; 
unsigned char cloneInfo[400]; 
long shareldx; 

char name[64] ; 

char SAname[64]; 
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/#esssssssebosstsecseckscasseccessosteese sess see soe seesessaeecessese 
/* Declares for working with a PKA token 
| Reaeeeseeseasat seccess sees senses sense ee meset Soe eee se os aee oe sues 
long pub_sec_len; /* Public section length 
long prv_sec_len; /* Private section length 
long cert_sec_len; /* Certificate section length 
long info_subsec_len; /* Information subsection length 
long offset; /* Offset into token 
long tempOffset; /* (Another) Offset into token 
long tempLength; /* Length variable 
long tempLenl, tempLen2; /* temporary length variables 
char cloneShare[] = "cloneShareQ0"; /* Base cloning share filename 
long count; /* Number of bytes read in from file 
decimal(15,5) shareParm; /* Packed 15 5 var used for converting 
/* from packed 15 5 to binary. Numeric 
/* parms on iSeries are passed as dec 15 
FILE *fp; /* File pointer 
if (argc < 5) /* Check number of parameters passed in 


printf("Need Share index, Receiver name, SA name, and cert\n"); 
return 1; 


} 


/* Convert the packed decimal 15 5 parm 
/* to binary. 

memcpy (&shareParm, argv[1],sizeof(shareParm) ); 

shareIdx = shareParm; 


memset(name,' ',64); /* Copy the Private key name parm to a 
memcpy (name,argv[2],strlen(argv[2])); /* 64 byte space padded var. 
memset (SAname,' ',64); /* Copy the Share Admin name parm to a 
memcpy (SAname, argv[3],strlen(argv[3]));/* 64 byte space padded var. 
fp = fopen(argv[4],"rb"); /* Open the file containing the token 
if (!fp) 

{ 

printf("File %s not found.\n",argv[4]); 

return 1; 

} 
memset (token,0,2500) ; /* Read the token from the file 


count = fread(token,1,2500, fp); 
fclose(fp); /* Close the file 
/* Determine length of token from length 


/* bytes at offset 2 and 3. 
token_len = ((256 * token[2]) + token[3]); 


if (count < token_len) /* Check if whole token was read in 
{ 
printf("Incomplete token in file\n"); 
return 1; 


} 


[KERR KKK AKER A KKK A KKK IKKE KK KEK KKK KKK IKEA KKK IKKE KKK ERK KK | 


/* Find the certificate offset in the token */ 
/* x/ 
/* The layout of the token is x/ 
/* x/ 
/* - Token header - 8 bytes - including 2 length bytes x/ 
/* - Public key section - length bytes at offset 10 overall «/ 
/* - Private key name - 68 bytes */ 
/* - Certificate section x/ 
/* x/ 


[KERR KKK AKER AKER A KKK AK KEK KKK KKK KKK KA KEKE AK KEK AKER AKER KK | 


pub_sec_len = ((256 * token[10]) + token[11]); 
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offset = pub_sec_len + 68 + 8; /* Set offset to certiicate section */ 


/* Determine certificate section x/ 

/* length from the length bytes at */ 

/* offset 2 of the section. */ 
cert_sec_len = ((256 * token[offset + 2]) + token[offset + 3]); 


[BRK RK ERA KK RA KKK A KKK AK KEK KKK KKK A KEK AKKEAKK ERK | 
/* Open and read the clone file x/ 
[RRR KER KKK AKER A KK KAKA KK EAR KKK KER AKEEAKK EEK | 
/* Build path name from the base x/ 


/* file name and the index */ 
if (shareIdx < 9) cloneShare[11] = '0' + shareldx; 
else 
cloneShare[10] = '1'; 
cloneShare[11] = '@' + shareIdx - 10; 
} 
fp = fopen(cloneShare,"rb"); /* Open the file with the share */ 
if (!fp) 
{ 


printf("Clone share file %s not found.\n",cloneShare) ; 
return 1; 


} 
/* Read in the length of the KEK x/ 
count = fread((char*) &cloneInfoKeyLength,1,4, fp) ; 


if (count < 4) /* Check if there was an error */ 


printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 

fclose(fp); 

return 1; 


} 
/* Read in the Key encrypting key x/ 
count = fread((char*)cloneInfoKey,1,cloneInfoKeyLength, fp) ; 


if (count < cloneInfoKeyLength) /* Check for an error reading */ 


printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 

fclose(fp); 

return 1; 


} 


/* Read in the length of the clone info */ 
count = fread((char*)&cloneInfoLength,1,4, fp); 


if (count < 4) /* Check for an error */ 


printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 

fclose(fp); 

return 1; 


} 


/* Read in the clone info x/ 
count = fread((char*)cloneInfo,1,cloneInfoLength, fp) ; 


if (count < cloneInfoLength) /* Check for an error */ 
{ 
printf("Clone share file %s contains invalid data.\n", 
cloneShare) ; 
fclose(fp); 


248 _ iSeries: Cryptographic hardware 


return 1; 


} 


fclose(fp); /* Close the file */ 
[ERK KER AKER KK EKA KEI K KR KKK IKKE KKK AKER KK AK KEK AKER AKER KKK | 

/* Install the share */ 

[ERR KER RRR AK ERIK EKA K KEK KK EAR KEK KKK IKEA IKEA KEIR KER AKER AKER | 
memcpy ((void*)rule_array,"INSTALL ",8); /* Set rule array */ 


rule_array_count = 1; 


CSUAMKD( &return_code, &reason_code, &exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
&shareldx, 
name, 

SAname, 
&cert_sec_len, 
&token[offset] , 
&cloneInfoKeyLength, 
cloneInfoKkey, 
&cloneInfoLength, 
cloneInfo); 


if (return_code > 4 ) 


printf("Master Key Distribution Failed : return reason %d/%d\n", 
return_code, reason_code); 
return 1; 


else 


{ 

printf("Master Key share %d successfully installed.\n",shareldx) ; 
printf("Return reason codes %d/%d\n", return_code, reason_code) ; 
return 0; 


} 
} 


Example: ILE RPG program for installing a master key share 
Change this program example to suit your needs for installing a master key share. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKKKKK KK KKK KKK KEK KEK KERR KR KERR KKK ERE KR ER KERR EER RK RRR KER ERR RRR 
D* PUTSHARE 

Dx« 

D* Sample program to install a master key share as part of 

Dx the master key cloning process. 

Dx 

Dx 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
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Dx (SC31-8609) publication. 

Dx 

D* Parameters: Share number 

D* Name of share receiver private key 

Dx Name of certifying key 

Dx Path name of stream file containing sender certificate 
Dx« 

D* Example: 

D* CALL PGM(PUTSHARE) PARM(2 RECVR SAKEY SENDER.PUB) 

Dx 

D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(PUTSHARE) SRCFILE(SAMPLE) 

D* CRTPGM PGM(PUTSHARE) MODULE (PUTSHARE) 

Dx BNDDIR(QCCA/QC6BNDDIR) 

Dx« 

D* Note: Authority to the CSUAMKD service program 

Dx in the QCCA library is assumed. 

Dx« 

D* The Common Cryptographic Architecture (CCA) verbs used is 
D* Master_Key Distribution (CSUAMKD). 

Dx« 

DAKAR KKKK KKK KEKE KKK KKK KERR KERR RRR KERR ERR RRR KR ERR RRR RRR RR RERRRRERR 
DeeSSSee aes a oee seas sesso ssasa sas ecsee sees ese se Ssasaessesea— 

D* Declare variables used by CCA SAPI calls 

[De 

Dx ** Return code 

DRETURNCODE S 9B 0 

D« ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXTTDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Token length 

DTOKENLEN S 9B 0 INZ(2500) 

Dx ** Token and array for subscripting 

DTOKEN DS 2500 

DTOKENARRAY 1 DIM(2500) 

Dx xx Private key name 

DPRVNAME S 64 

Dx ** Certifying key name 

DCERTKEY S 64 

Dx 

DLSTRUCT DS 

Dx ** Clone KEK length - one is binary form and the 
Dx ** other is used for reading the value from a file 
DCLONEKEKL 9B 0 INZ(500) 

DCLONEKEKLC 1 4 

Dx ** Clone info length - one is binary form and the 
Dx xx other is used for reading the value from a file 
DCLONEINFOLEN 9B 0 INZ(400) 

DCLONEINFOLENC 5 8 

Dx ** Cloning key-encrypting-key 

DCLONEKEK S 500 

Dx ** Cloning info 

DCLONEINFO S 400 

Dx ** Share index 

DSHAREIDX S 9B 0 

Dx ** Data structure for aligning 2 bytes into 
Dx ** a2 bytes integer 

DLENSTRUCT DS 2 

DMSB 1 1 

DLSB 2 2 
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DLENGTH 1 2B 0 


Dx xx Certificate section length 
DCRTSECLEN S 9B 0 

Dx ** Public key section length 
DPUBSECLEN S 9B 0 

Dx ** Index into Token array 

DTKNINDEX S 9B 0 

Dx ** Number of bytes to read froma file 
DINLEN S 9B 0 

Dx ** File descriptor 

DFILED S 9B 0 

Dx ** File path and length 

DPSTRUCT DS 

DPATH 80 INZ(*ALLX'00') 
DSIDX 11 12B 0 

DPATHLEN S 9B 0 

Dx ** Open Flag - Open for Read only 
DOFLAGR S 101 0 INZ(1) 

Dx xx Base name of file to store cloning share 
DSHAREFILE S 12 INZ('cloneShareQ0' ) 
Dx 


DA KRAKKKKKK KK KKK KKK ERK KEKE RRR RRR KK KERR RRR RRR RR RER RRR KEKE RRR 


D* Prototype for Master_Key Distribution (CSUAMKD) 


DA KRKK KARR KK KKK KKK ERK KK ERK KKK KKK KKK KEK KERR KKK KER KK KERR RRR 


DCSUAMKD PR 

DRETCOD 9B 0 

DRSNCOD 9B 0 

DEXTDTALN 9B 0 

DEXTDT 4 

DRARRYCT 9B 0 

DRARRY 16 

DSHRINDX 9B 0 

DKYNAM 64 

DCRTKYNAM 64 

DCRTL 9B 0 

DCRT 2500 OPTIONS (*VARSIZE) 
DCLNKEKL 9B 0 

DCLNKEK 1200 OPTIONS (*VARSIZE) 
DCLNL 9B 0 

DCLN 400 OPTIONS (*VARSIZE) 
Dx« 


DA KRKKKKKK KK KKK KKK ERK KK RRR KKK KEK KK KKK KK RR KKK KER KK RRR KR ERK ER 
Dx Prototype for open() 

DA KRK KKK KKK KKK KKK ERK KK ERK KKK KKK KKK KKK RR KKK KER RK RE KKK KERR ER 
Dx value returned = file descriptor (0K), -1 (error) 


Dopen PR 9B @ EXTPROC('open') 

Dx path name of file to be opened. 

D 128 OPTIONS (*VARSIZE) 

Dx Open flags 

D 9B 0 VALUE 

Dx (OPTIONAL) mode - access rights 

D 10U © VALUE OPTIONS (*NOPASS) 
D« (OPTIONAL) codepage 

D 10U © VALUE OPTIONS (*NOPASS) 
Dx« 


DARK AKKKKKK KKK RK KKK KEK K KKK KEK KKK KKK KER KK KERR RRR KER KK RRR KR E RK KR ERRERRREKRKE RRR 
D* Prototype for read() 

DARA KKKKKK KKK KKK KEK KKK ERK KKK KKK KER KEK KERR KKK KER RK RE KKK RRR 

Dx value returned = number of bytes actually read, or -1 


Dread PR 9B 0 EXTPROC('read') 
Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx Input buffer 

D 2500 OPTIONS (*VARSIZE) 
D* Length of data to be read 

D 9B 0 VALUE 

Dx 
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DA KKRK KKK KKK KER KKK KEK KKK KKK KK RRR RRR KKK KER K RRR RR KK RRR KKK KEKE KK ERE RR RRR KR ER 
D* Prototype for close() 

DA KRKK KKK KKK KEKE KKK KKK KERR KERR KEK RRR RR RRR KEKE RRR KER RE RRR RRR RRR RE RERERERE 
Dx value returned = 0 (OK), or -1 


Dclose PR 9B 0 EXTPROC('close') 

Dx File descriptor returned from open() 

D 9B 0 VALUE 

Dx 

Peace SSesseosseseccosseaseSsceseceesceseeseeSse soe cesseecescess 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Dk¥seSeeessoen soe ce so see eee Sec eS ee eee eee See ee See ace te seese 
DMSG S 75 DIM(7) CTDATA PERRCD(1) 

D DS 

DMSGTEXT 1 80 

DSAPI 1 7 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMSGLENGTH Ss 9B 0 INZ(80) 

DMESSAGEID S 7 INZ(' ms) 
DMESSAGEFILE S 21 INZ(' ') 
DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ") 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B © INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(O) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx« 

CX KKK KKK KKK KK KKK KR KK ERK KEK ERE KKK KERR KEKE KR ERE RK RR ERE RRR EKER 
Cx START OF PROGRAM * 
Cx * 
Cc *ENTRY PLIST 

C PARM SINDEX 15 5 
C PARM PRVKEY 32 
C PARM SAKEY 32 
C PARM FILEPARM 32 


CRRA KKK KKK KK KKK KR KK ERK EK ERE KK EKER KERR EKER EKER KERR ERE RE RK ERR ERE 


Cx Open certificate file 
CR K KK KKK KKK KKK KKK EKER KER ERE KKK KEK KERR EKER ER ERR RR ERE RRR ERREERE 


Cx Fesseseeebeeseeeceees= * 

Cx  »** Build path name * 

Cx feseme seen eee see eee eee * 

C EVAL PATHLEN = %LEN(%TRIM(FILEPARM) ) 

C PATHLEN SUBST FILEPARM: 1 PATH 

Cx Posse ce see came eee emia — * 

Cx * Open the file * 

Cx* (ossaecseeosesceoeses= * 

C EVAL FILED = open(PATH: OFLAGR) 

Cx Pace caee aime meee eminem ae * 

Cx »* Check if open worked * 

Cx« Lecseeeseeocseanecaeces * 

C FILED IFEQ -1 

Cx* Pace eka scot ene hee e cee ees See cme * 

Cx * Open failed, send an error message * 

Cx« cane aes eeees Sete se Seeeseeeeeseoesscas * 

C MOVEL MSG(1) MSGTEXT 

C EXSR SNDMSG 

C RETURN 

Cx 

C ENDIF 

Cx HessSsslsseseeosssesecsscseossossecscsssossleseSsccsesces * 
Cx * Open worked, read certificate from file and close file * 
Cx FicSe see sees tesa ess c ee eee ee eee Sse eee eee Seca sess eee * 
C EVAL TOKENLEN = read(FILED: TOKEN: TOKENLEN) 
C CALLP close (FILED) 

Cx« 


iSeries: Cryptographic hardware 


Cx * Check if read operation was OK * 
Cx* Stash aS ere nd nelle * 

C TOKENLEN IFEQ -1 

C MOVEL MSG(2) MSGTEXT 
C EXSR SNDMSG 

C ENDIF 

Cx* 

Cx* Hissovessacsaceeeseesosssseceoacisose coke * 
Cx * Check if certificate length is valid * 
Cx * The length bytes start at position 3 * 
Cx* et ei pio os se fw ssi * 

C EVAL MSB = TOKENARRAY (3) 
C EVAL LSB = TOKENARRAY (4) 
C LENGTH IFLT TOKENLEN 

Cx* a aee ee ee Se acim eee ee eee a ies * 
Cx * Certificate length is not valid * 
Cx* I a ttl ie eo th es * 

C MOVEL MSG (3) MSGTEXT 
C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx« 


CK KKK KEKE KK KKK KKK KEE KEK KKK ERK KK EKER KKK RK KKK EKER KERR ERE RE RK ERR ERE 
Cx Find the certificate in the token 

Cx* 

Cx The layout of the token is 

Cx« 

Cx - Token header - 8 bytes - including 2 length bytes 

Cx - Public key section - length bytes at position 2 (11 overall) 
Cx - Private key name - 68 bytes 

Cx - Certificate section 

Cx 

Cx Note: 1 is added because RPG arrays start at 1. 

CR KKK KK KK KKK KKK KKK KEKE RK ER ER KEK KKK ERK RRR KERR EKER ERR ER ERR ERE REE 


C EVAL MSB = TOKENARRAY (11) 

C EVAL LSB = TOKENARRAY (12) 

C EVAL PUBSECLEN = LENGTH 

C EVAL TKNINDEX = PUBSECLEN + 68 + 8 + 1 
Cx* 

Cx* Se a a i ta a a i a hs nc * 

Cx * Determine length of certificate section * 

Cx * Length bytes are at position 2 of the * 

Cx * section. 

Cx* Scat SaaS ae Saeko eee eee nce * 

C EVAL MSB = TOKENARRAY(TKNINDEX + 2) 
C EVAL LSB = TOKENARRAY(TKNINDEX + 3) 
C EVAL CRTSECLEN = LENGTH 

Cx* 


CR KKK KK KKK KKK KEKE KR EKER KER ERE KK EKER KERR EK ERR ERE ERR ER ERE ERE 


Cx Open and read the clone file 
CXR KKK KKK KKK KK KKK KR KEKE KK KK ERK KK EKER KKK EKER KER ERE RR ER ERK RK ER 


Cx« Mosuseseeeseceee setae cas seeseesecescoessoes * 

Cx »* Set share index number * 

Cx * (Convert from packed 15 5 to binary) * 

Cx« Mocseeseeeeseeaseceess ans seSeees ee ee aceeesee * 

C Z-ADD SINDEX SHAREIDX 

Cx ** Build path name 

C MOVEL *ALLX'00' PATH 

C MOVEL SHAREFILE PATH 

Cx «x Adjust two digits on file name by adding to their 
Cx ** character value 

C SIDX ADD SHAREIDX SIDX 

Cx xx If the index is greater than or equal to 10 

Cx ** then add 246 to force the first character to change 
C SHAREIDX IFGE 10 

C SIDX ADD 246 SIDX 
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C ENDIF 


C* 

Cx ** Open the file 

Cx* 

C EVAL FILED = open(PATH: OFLAGR) 

Cx 

Cx ** Check if open worked 

Cx 

C FILED IFEQ -1 

Cx« 

Cx *x Open failed, send an error message 

C* 

C MOVEL MSG(4) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ELSE 

Cx 

Cx ** Qpen worked, read in the clone information and close file 

Cx 

C SETON Ql 
C Z-ADD 4 INLEN 

C EVAL INLEN = read(FILED: CLONEKEKLC: INLEN) 

Cx« 

Cx« teescsacsonn oaeasnassocecolscceeceoaseee * 

Cx * Check if read operation was OK * 

Cx avo aa cae se eee ee eee ete tees Sea * 

C INLEN IFNE 4 

C MOVEL MSG(5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

Cx 

C «61 EVAL INLEN = read(FILED: CLONEKEK: CLONEKEKL) 
Cx« 

C  O1INLEN IFNE CLONEKEKL 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

Cx* 

C «61 Z-ADD 4 INLEN 

C «61 EVAL INLEN = read(FILED: CLONEINFOLENC: INLEN) 
Cx« 

Cx« tecewscesessecsecsnssccsceseesectossceS * 

Cx * Check if read operation was OK * 

(a Pe cceaeecese ese eee eee ee eee ees eee * 

C  O1LINLEN IFNE 4 

C MOVEL MSG(5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

Cx* 

C: 01 EVAL INLEN = read(FILED: CLONEINFO: CLONEINFOLEN) 
Cx* 

Cx feceteseecs eee eee eee cece cee eee ete * 

Cx * Check if read operation was OK * 

Cx« seceewessaeee Sect saceoceeocelcesecseS * 

C  O1INLEN IFNE CLONEINFOLEN 

C MOVEL MSG (5) MSGTEXT 

C EXSR SNDMSG 

C SETOFF 01 
C ENDIF 

Cx 

C CALLP close (FILED) 

C NOL SETON LR 
Cx« 


CK KKK KKK EK KKK KKK KR KK ERK KK ERE KK EKER KEK KEKE KR ER ERR RR EKER ERR EKER E 
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Cx Obtain a certificate 
CK KK KK KEKE KKK KEKE KR EKER KER ERK KK EKER RRR ERE ER ER ERE RR ERE RK RKERRERRE 


Cx* 
Cx* 
Cx« 
C 
Cx« 
Cx* 
Cx« 
C 
C 
Cx* 
Cx* 
Cx« 
C 
C 
Cx* 
Cx« 
Cx« 
C 
C 
Cx« 
Cx« 
Cx« 


AAO OOOAO:090000:0 


Cx 


we wwe ew ew ew ew ew ew ew ee ew ee ew ee ee ee ee ee ee ee ee ee ee ee * 
* Set share index number * 
we www ew ew ew ew ee ew ee ew ee ee ee ee ew ee ee ee ee ee ee ee ee * 
Z-ADD SINDEX SHAREIDX 
wee wee eww ew ew ee ew ee ew ee ee ee ee ee ee ee ee ee ee ee ee * 
* Set private key name * 
www ww ew ew ew ee ew ee ee ee ee ee ee ee we ee ee ee ee ee ee * 
EVAL LENGTH = %LEN(%TRIM(PRVKEY) ) 
SUBST PRVKEY:1 PRVNAME 
wee we ew ew ew ew ew ee ee ew ee ee ew ee ee ee ee ee ee ee ee ee ee * 
* Set certifying key name * 
wee ewww ewe ew ee ew ew ew ew ew ee ee ee ee ee ee ee ee ee ee ee ee * 
EVAL LENGTH = %LEN(%TRIM(SAKEY) ) 
SUBST SAKEY:1 CERTKEY 
we ww ewe ew ew ew ee ew ee ee ee ee ee ee ee ee ee ee ee ee ee ee * 
* Set the keywords in the rule array * 
we ww eww ew ew ee ew ee ew ee ee ee ee ee ee ee ee ee ee ee eee * 
MOVEL ‘INSTALL ' RULEARRAY 
Z-ADD 1 RULEARRAYCNT 
we we ew wee ew ee ew ee ee ee ee ee ee ee ee ee ee ee * 
* Call Master Key Distribution SAPI * 
we www ew ew ew ew ew ew ew ee ee ew ee ee ee ee ee ee ee ee ee * 
CALLP CSUAMKD (RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT : 
RULEARRAY : 
SHAREIDX: 
PRVNAME: 
CERTKEY: 
CRTSECLEN: 
TOKENARRAY (TKNINDEX) : 
CLONEKEKL: 
CLONEKEK: 
CLONEINFOLEN: 
CLONEINFO) 
IFGT 4 
MOVEL MSG (6) MSGTEXT 
MOVE RETURNCODE FAILRETC 
MOVE REASONCODE FAILRSNC 
MOVEL "CSUAMKD' SAPI 
EXSR SNDMSG 
RETURN 
ENDIF 
MOVEL MSG(7) MSGTEXT 
EVAL %SUBST(MSGTEXT: 32: 12) = 
%SUBST(PATH: 1: 12) 
EXSR SNDMSG 
ENDIF 
SETON LR 


CR KKK KKK KEK KKK EKER RE K ERK ER ERK RRR KERR RK EK EER EKER KERR EKER KERR ERREREREE 


Cx Subroutine to send a message 
CK KKK KKK KKK KK KKK KKK KEK KEK ERK KK KK ER KKK RK KEK KER ERK RR ERE RE RRR RR ERE 
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C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 

(a 


** 

The certificate file could not be opened. 

There was an error reading from the certificate file. 

The length of the certificate is not valid. 

The clone share file could not be opened. 

The clone share file either could not be read or has invalid data. 
CSUAMKD failed with return/reason codes 9999/9999. 

The share was successfully installed. 


Example: ILE C program for listing retained keys 
Change this program example to suit your needs for listing retained keys. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


peeseeseessseaseseseseesaee see ase eseeseGsens sesseeseasesscssees=—=s> */ 
/* List the names of the RSA private keys retained within the x/ 
/* 4758. */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 x/ 
/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: Input format is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(LISTRETAIN) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the card with the profile is */ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic_Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Access Control_Initialization (CSUAACI). x/ 
/* x/ 
/* Use these commands to compile this program on iSeries: x/ 
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/* ADDLIBLE LIB(QCCA) 
/* CRTCMOD MODULE(LISTRETAIN) SRCFILE (SAMPLE) 
/* CRTPGM PGM(LISTRETAIN) MODULE (LISTRETAIN) 


/* BNDSRVPGM(QCCA/CSNDRKL) 

/* 

/* Note: Authority to the CSNDRKL service program in the 
/* QCCA library is assumed. 

/* 


/* The Common Cryptographic Architecture (CCA) verb used is 
/* Retained Key List (CSNDRKL). 

/* 

#include <string.h> 

#include <stdio.h> 

#include "csucincl.h" 


void main(void) 


{ 

[eos soeesasesstesasscueoswssssassessesssase ss sssesesesecs seceS 
/* standard CCA parameters 
[eeeceseeseeeetesessicentetessere Hees ese se eeet ee Seas Se See 
long return_code; 

long reason_code; 

long exit_data_length; 

unsigned char exit_data[2]; 

long rule_array_count; 


unsigned char rule array[2] [8]; 


unsigned char key_label_mask[64]; 
unsigned char key_label [500] [64]; 


long retain_key_count; 

long key_label_count = 500; 

int k; 

fescue seeseesesss eee escose ese aea nes seceeeee sen seeoseeaeesseees 
/* Set up label mask, ie. which key name to retrieve. 

/* *.*.*.*.*.*,.* iS a wildcard for all keys. 
[RsssoteceseassseseeaeasseceSeesess SoceSaseeaeaSseeaeeqeeseea= 
memset (key_label, 0x00, sizeof(key_label) ); 

memset (key_label_mask, ' ', sizeof(key_label_mask)); 

memcpy (key_label_mask,"*.*.*.*.*.*.*",13); 


rule_array_count = 0; 


CSNDRKL(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
key_label_mask, 
&retain_key_count, 
&key_label_count, 
(unsigned char*)key_ label); 


if (return_code != 0) 


{ 


printf("Retained Key List failed with return/reason %d/%d \n", 


return_code, reason_code) ; 
returns; 
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*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 


*/ 
*/ 
*/ 
*/ 


*/ 
*/ 
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[xeeebeeesaaSesenesseesesesoSs eases eee eases ee este ease «/ 
/* Display number of keys retained/returned. */ 
eescesscssssecsseseessssscasesseceesssaseese lease ese Se cee -tss= */ 


printf("Retained key count [%d]\n",retain_key count); 
printf( "No. of key labels returned [%d]\n",key_label_count); 
if (key_label_count > 0) 


{ 
/ ¥eseoteccesesscasesseteessossosseesesescs secu saseSlSeceseeee */ 
/* Display the names of each key returned. */ 
{ $eeteesesSsseeseseseseese eerste sees see ees ce eeaSaeaece Sosa! */ 


printf("Retain list = \n" ); 

for (k = 0 ;k < key_label_count; k++) 
{ 
printf( "[%.64s]\n",key_label[k]); 
} 

} 

} 
} 


Example: ILE RPG program for listing retained keys 
Change this program example to suit your needs for listing retained keys. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DARK RKKKKK KK KER KKK KKK KK ERK KKK KEK KK ERR KK RR KKK KER KK RRR KERR EERE KERK 
Dx« 

D* List the names of the RSA private keys retained within the 
Dx 4758. 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 
Dx (SC31-8609) publication. 

Dx 

D* Parameters: None 

Dx 

D* Example: 

D* CALL PGM(LISTRETAIN) 

Dx 


D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(LISTRETAIN) SRCFILE(SAMPLE) 

D* CRTPGM PGM(LISTRETAIN) MODULE(LISTRETAIN) 

Dx BNDSRVPGM(QCCA/CSNDRKL) 

Dx 

D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Retained_key List (CSNDRKL) 


Dx« 

D* Note: Authority to the CSNDRKL service program in the 
Dx QCCA library is assumed. 

Dx 

Dx« 
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D* Note: This program assumes the card with the profile is 


Dx already identified either by defaulting to the CRPQ1 
Dx device or by being explicitly named using the 
Dx Cryptographic_Resource Allocate verb. Also this 
Dx device must be varied on and you must be authorized 
Dx to use this device description. 

Dx« 

DA KRAKKKKKKK KK KKK KEKE KKK KERR KEKE KR KK KER KERR ERK RRR ER RK RR EKER EER ERR 
DeertssooossoseceacusceeSsoseesscccoceossssscosccess 

D* Declare variables for CCA SAPI calls 
PxeerseoossestacsscscecsseslesSeccossoeessssosscses= 

Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 

DEXITDATALEN S 9B 0 

Dx ** Exit data 

DEXITDATA S 4 

Dx ** Rule array count 

DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx ** Key label mask 

DKEYLBLMASK S 64 

Dx ** Key count 

DKEYCOUNT S 9B 0 

Dx ** Label count 

DLABELCOUNT S 9B 0 

Dx ** Label list and label array 
DLABELLIST DS 3200 

DLABELS 64 DIM(50) 

Dx ** Loop counter 

DI S 9B 0 

Dx« 


DA KRKKKKKKK KK KKK KEKE KKK KERR KERR R KK KERR RRR RRR RR ERR RRR KER ERR 


D* Prototype for Retained Key List 


DA KRKKKKKK KK KKK KKK ERK KK ERK KKK KKK KKK KERR KEKE KKK ERK KEKE RRR ERR ER 


DCSNDRKL 
DRETCODE 
DRSNCODE 
DEXTDTALEN 
DEXTDTA 
DRARRAYCT 
DRARRAY 
DKYLBLMSK 
DKYCOUNT 
DLBLCOUNT 
DLBLS 


DMSG 
DMSGLENGTH 
D 

DMSGTEXT 
DNUMKEYS 
DNUMLABELS 
DDSPLBL 
DFAILRETC 
DFAILRSNC 
DMESSAGEID 
DMESSAGEFTLE 
DMSGKEY 
DMSGTYPE 


PR 


** 
** 


NANnNnn 


9B 0 
9B 0 
9B 0 
4 
9B 0 
16 
64 
9B 0 


Declares for sending messages to the 


75 

9B 0 
1 75 
il 3 
25 26 
2 65 
41 44 
46 49 
7 
21 
4 
10 


job log using the QMHSNDPM API 


DIM(4) CTDATA PERRCD(1) 


INZ(75) 


INZ(' ') 

INZ(' ') 
INZ(' ') 

INZ('*INFO i} 
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DSTACKENTRY S 10 INZ('* ») 


DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Dx 

CR KKK KKK KKK KK EKER KKK ERK ER ERE RRR K EKER KEK ERR ERE RRR ERE REE ERR 
Cx START OF PROGRAM * 
Cx * 
CkSasaeSaSaceSsSseee a seese seas eeeea=seas sao S = SSeS ess ==-=S=e5 * 
Cx No rule array keywords * 
CdeeseceeoessesesesensadereenseeuneesesseeEere eee eto ceseese * 
C Z-ADD 0 RULEARRAYCNT 
Cxkeceesosecescessesossoesessessesel ec Sse ssc SeSesesessssceeces * 
Cx Get up to 50 labels * 
Chee skesmeseeeeneee ened ses ene seer eecse see eee eRe eee teense ee * 
C Z-ADD 50 LABELCOUNT 

(Rees ecnece esas seee eee eee sse seems seeders eee emeeeeeenesecee * 
Cx Set the mask to everything * 
Ckeateaasa sso lesa S Sea ae Soa saae as esaS saa > aoe eS eee == saa Se * 
C MOVEL ne KEYLBLMASK 

Okeesteeseese ese esses eds eeeseencee sen eHe ese enweHesnecessess * 
Cx Call Retained Key List SAPI * 
Ckeeeeessecessessclosscasosltessesesce sss scesescessescseceecus * 
C CALLP CSNDRKL (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT : 

C RULEARRAY : 

C KEYLBLMASK: 

C KEYCOUNT: 

C LABELCOUNT: 

C LABELLIST) 
C¥sessessSecescecceesesss * 

Cx Check the return code * 

Ckscteasiccceeeseeeceeesss * 

C RETURNCODE IFGT 4 

Cx Hesssesssssessesscseses * 

Cx * Send error message * 

Cx Fosse eet eeeeese see ese ss * 

C MOVE MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx 

C ELSE 

Cx« 

Ck Hes cSeceeseescece secase * 

Cx * Check number of keys * 

CeO ees os ee esse ce ces see eee * 

C LABELCOUNT IFEQ 0 

Cx Keaeseeseeaes a= assesses aa =sassoesessees— * 

Cx * Send message saying there are no keys * 

Cx* (asahecr ah haben cee toce eee cecem ence hiooe * 

C MOVE MSG(2) MSGTEXT 

C EXSR SNDMSG 

Cx« 

C ELSE 

Cx 

Cx KeeSsesee Sse sae seaeeee ase Sa eae Seee * 

Cx * Send message with number of keys * 

Cx Wesescecseee see aeecessceeece seuss sce * 

C MOVE MSG (3) MSGTEXT 

C MOVE KEYCOUNT NUMKEYS 

C MOVE LABELCOUNT NUMLABELS 

C EXSR SNDMSG 
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KK 
cs 
Th 
00 
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Cx keotnoecsssss leans eee sees ceeS * 
Cx * Display each key label up to 50 * 
Cx kobe See sss e ce eee eens ae seecee ea seeS * 

C MOVE MSG(4) MSGTEXT 
C FOR I=1 BY 1 TO LABELCOUNT 
C MOVEL LABELS (I) DSPLBL 
C EXSR SNDMSG 

C ENDFOR 

Cx* 

C ENDIF 

C ENDIF 

Cx* 

C SETON 

Cx 


CR KKK KKK KKK KK KKK KR EKER KER EKER KEK ERK RR ERE ER EKER KERR ERE RR RR ERR 
Cx Subroutine to send a message 
CR KKK KKK KEK KKK KKK KR EKER KER ERK KK EKER RRR EKER EKER KERR ERE RK RKERRERE 


C SNDMSG BEGSR 


C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


NDRKL failed with return/reason codes 9999/9999 
ere are no retained keys in the 4758 
0 keys were found and 00 labels returned 


] 


Example: ILE C program for deleting retained keys 
Change this program example to suit your needs for deleting retained keys. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
[x 
/* 
/* 


Delete a retained key from the 4758 


COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


This material contains programming source code for your 
consideration. These examples have not been thoroughly 

tested under all conditions. IBM, therefore, cannot 

guarantee or imply reliability, serviceability, or function 

of these program. All programs contained herein are 

provided to you "AS IS". THE IMPLIED WARRANTIES OF 
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
these programs and files. 


Note: Input format is more fully described in Chapter 2 of 
IBM 4758 CCA Basic Services Reference and Guide 
(SC31-8609) publication. 


Parameters: 
none. 


Example: 
CALL PGM(DLTRTNKEY) (SSLPRIV.KEY.ONE) 
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/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


Note: This program assumes the card with the profile is 


already identified either by defaulting to the CRPO1 


device or by being explicitly named using the 
Cryptographic_Resource_ Allocate verb. Also this 


device must be varied on and you must be authorized 


to use this device description. 


The Common Cryptographic Architecture (CCA) verb used is 


Retained Key Delete (CSNDRKD). 


Use these commands to compile this program on iSeries: 

ADDLIBLE LIB(QCCA) 

CRTCMOD MODULE(DLTRTNKEY) SRCFILE(SAMPLE) 

CRTPGM PGM(DLTRTNKEY) MODULE (DLTRTNKEY) 
BNDSRVPGM(QCCA/CSNDRKD) 


Note: Authority to the CSNDRKD service program in the 
QCCA library is assumed. 


#include <string.h> 
#include <stdio.h> 
#include "csucincl.h" 


#define OK 0 
#define WARNING 4 


void main(int argc, char * argv[1]) 


{ 


[Reasereecesmes=sesseenssecs essere soo saes=asesseaseseese-o=—=5 
/* standard CCA parameters 
[Reseeeeeeescoseeseteasseneseess-ontacle sear te oe ete 
long return_code; 

long reason_code; 

long exit_data_length; 

unsigned char exit_data[2]; 

long rule_array_count = 0; 


unsigned char rule_array[1] [8]; 
unsigned char key_label[64]; 


if (argc < 1) 
{ 


printf("Key label parameter must be specified.\n"); 
returns; 


[saa ciamaaeee ess ane ee sess see aaa eee as aes See eo — 


memset (key_label, ' ', 64 ); 
memcpy(key_label, argv[1], strlen(argv[1]) ); 


/* Call the Retained Key List SAPI 
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ae «/ 


*/ 


ania simnis «/ 


amioseais «/ 


*/ 


CSNDRKD(&return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(unsigned char*)rule_array, 
key_label); 


| a a ee te ee nee ee */ 
if ( (return_code == OK) || (return_code == WARNING) ) 
{ 


printf("Request was successful\n"); 
returns 


else 
{ 
printf("Request failed with return/reason codes: %d/%d \n", 
return_code, reason code); 
returns 


} 


} 


Example: ILE RPG program for deleting retained keys 
Change this program example to suit your needs for deleting retained keys. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRKK KAKA KKK KKK KEKE KKK ERK KKK KKK KER KKK ERK KK RRR RK RE KK RR ERK 
D* DLTRTNKEY 

Dx« 

D* Sample program to delete a retained key from the 4758 

Dx« 

Dx« 

D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 

Dx« 

D* This material contains programming source code for your 

D* consideration. These example has not been thoroughly 

D* tested under all conditions. IBM, therefore, cannot 

D* guarantee or imply reliability, serviceability, or function 
D* of these programs. All programs contained herein are 

D* provided to you "AS IS". THE IMPLIED WARRANTIES OF 

D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

D* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for 
D* these programs and files. 


Dx« 

Dx« 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx 


D* Parameters: 
D* Retained key label name 


D« (64 chacters - pad with blanks on the right) 
Dx« 

D* Example: 

Dx 


D* CALL DLTRTNKEY + 

D* 'PKA.RETAINED.KEY.123 
Dx« 

D* Use these commands to compile this program on iSeries: 

D* CRTRPGMOD MODULE(DLTRTNKEY) SRCFILE(SAMPLE) 

D* CRTPGM PGM(DLTRTNKEY) MODULE (DLTRTNKEY) 
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Dx BNDSRVPGM(QCCA/CSNDRKD) 


D« 

D* Note: Authority to the CSNDRKD service program in the 
Dx QCCA library is assumed. 

Dx 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Retained Key Delete (CSNDRKD) 


Dx 

DARK RK KKK KKK KER KK KEK KKK ERK KKK ERK KK RRR KERR KKK KER KEK RRR KK RR RRR KERR 
Dkeeeiaaaa apes eae ses seSse se Sesoesee lass eeSeeeSee= 
D* Declare variables for CCA SAPI calls 
DkseSssasesesasceseesenet eee sec cs ese e eee cee 
Dx ** Return code 

DRETURNCODE S 9B 0 

Dx ** Reason code 

DREASONCODE S 9B 0 

Dx ** Exit data length 
DEXITDATALEN S 9B 0 

Dx «x Exit data 

DEXITDATA S 4 

Dx ** Rule array count 
DRULEARRAYCNT S 9B 0 

Dx ** Rule array 

DRULEARRAY S 16 

Dx xx Retained key label 

DKEYNAME S 64 

Dx 


DARK KK KKK KKK KER KK KEK KKK ERK KKK ERK KEKE KEK KERR KKK KER KEK REE KK KERERE 


D* Prototype for Retained_Key Delete (CSNDRKD) 


DA KRRK KKK KKK KER KKK EK KKK ERK KKK KERR KEKE RK KR KKK KR ERR KR RRR KK KERR 


DCSNDRKD PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DKEYNAM 64 

Dx« 

[De ae een ee 
Dx ** Declares for sending messages to the 

D* ** job log using the QMHSNDPM API 

Dee aaa ea a Se a Sea a a a a ae Se eee eee 
DMSG 5 75 DIM(2) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(75) 

D DS 

DMSGTEXT 1 75 

DFAILMSGTEXT 1 50 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* a) 
DSTACKCOUNTER 5 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(Q) 

DBYTESOUT 5 8B 0 INZ(O) 

Dx 

CR KKK KKK KKK KK KKK KKK KEK KKK ERE KKK KERR K KERR ERE RE R EKER KERR EKER E 
Cx START OF PROGRAM * 
Cx* * 
C *ENTRY PLIST 

C PARM KEYNAME 

Cx« * 
CxseeSecsecsscsccsce bse ssccsesscssossSe sess ecscesisssosSscseeS * 
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** 


Cx Set the keywords in the rule array 


Cxkeeeseccsceeeeeteesces sees cesses eset 
C Z-ADD 0 

Ckereorescte cle see soe Seesce eee eeeet eos 
Cx Call Retained Key Delete SAPI 
CkseescescesesscssesecsecssssSsseseeecasess 
C CALLP CSNDRKD 

C 

C 

C 

C 

C 

C 

Cksosceesessascceccsceess * 

Cx Check the return code * 
(Ctasosseemeceessecesessee * 

C RETURNCODE IFGT 4 

Cx Fresca sesesoseseeesssoe = * 
Cx * Send error message * 
Cx keessaa=asa=ss=s5—5—S55= * 

C MOVE MSG (1) 

C MOVE RETURNCODE 
C MOVE REASONCODE 
C EXSR SNDMSG 

Cx« 

C ELSE 

Cx ASoescctesesoceeeceeseS * 
Cx * Send success message * 
Cx ASSosecuSsSeeSesosssssees * 

C MOVE MSG (2) 

C EXSR SNDMSG 

Cx 

C ENDIF 

Cx 

C SETON 

Cx 


(RETURNCODE: 
REASONCODE: 
EXITDATALEN: 
EXITDATA: 
RULEARRAYCNT: 
RULEARRAY : 
KEYNAME) 


MSGTEXT 
FAILRETC 
FAILRSNC 


MSGTEXT 


LR 


CR KKK KK KKK KKK KEKE KR ERE RK ER ER KKK EKER KKK ERE ER ER ERE RR EKER KEKE RRR 


Cx Subroutine to send a message 


CK KKK KKK KKK KKK KEK KERR EK KEK ERK KK EKER KKK RK KEK KER ERK RR ERE RRR ERR ERE 


C SNDMSG BEGSR 

CALL "QMHSNDPM' 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
PARM 
ENDSR 


BDOADMOaAOaAADAAaAAaAAaAAa 


* 


MESSAGEID 
MESSAGEFILE 
MSGTEXT 
MSGLENGTH 
MSGTYPE 
STACKENTRY 
STACKCOUNTER 
MSGKEY 
ERRCODE 


CSNDRKD failed with return/reason codes 9999/9999' 
The request completed successfully 


Troubleshoot the 4758 Cryptographic Coprocessor 


Use the methods below to tackle some of the basic problems that may occur with your 4758 Coprocessor. 
If the troubleshooting information does not address your problem, contact your service representative. 


Always assure that you have applied all current PTFs for the relevant products and programs. 


Using return codes 
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The primary method for detecting and troubleshooting problems is by monitoring return codes and reason 
codes. 


¢ A return code of 0 indicates successful completion. To provide some additional information, the 4758 
Coprocessor associates some non-zero reason codes with this return code. 


¢ A return code of 4 indicates that the application programming interface (API) has completed 
processing, but an unusual event occurred. It could be related to a problem created by the application 
program, or it could be a normal occurrence based on data that is supplied to the API. 


* A return code of 8 indicates that the API did not complete successfully. An application programming 
error most likely caused this. 


¢ A return code of 12 normally indicates some type of problem in the setup or configuration of your 
4758. This code means that the processing of the API did not complete successfully. 


¢ A return code of 16 normally indicates a severe error in Common Cryptographic Architecture 
Cryptographic Service Provider (CCA CSP), iSeries licensed internal code, or the 4758 Coprocessor 
licensed internal code. For these types of errors, you should contact your service representative. 


You can also troubleshoot problems by analyzing the messages that appear in the job log or in the system 
operator (QSYSOPR) queue. Generally, any event that sends a message to the job log also returns an 
associated return code and a reason code to the calling programming. Messages sent to the system 
operator message, if reporting a severe problem, will normally point to a source of additional information 
about the problem. Such information is intended for IBM service, and therefore you may not necessarily 
find them useful for problem determination. 


Common errors 


You should watch out for these common errors: 


¢ Have you installed the 4758 Coprocessor and the CCA CSP? The 2620 Cryptographic Processor 
and 2628 Cryptographic Processor - Commercial are completely separate solutions that work with the 
IBM CCA Services for iSeries. The 4758 Coprocessor and CCA CSP will not work with the 2620, the 
2628, or the IBM CCA Services. 


¢ Did you vary on the device? You cannot send any requests to your 4758 Coprocessor until you vary 
on the device. 


* Is the resource for the cryptographic device description a 4758 Cryptographic Coprocessor or a 
2620 or 2628? It should be a 4758 Cryptographic Coprocessor. 


¢ Is the 4758 Coprocessor finding a device? If you do not explicitly use the 
Cryptographic_Resource_Allocate API, you must name the cryptographic device CRPO1. If you do not 
name it that, the CCA cannot select any device. Either name the device CRPO1 or change your 
program to use the Cryptographic_Resource_Allocate CCA API to select the device. 


¢ Are you selecting the correct device? If you have a default device (for example, a device named 
CRP01) and an additional device, the 4758 Coprocessor will select the default device, unless you use 
Cryptographic_Resource_Allocate. 

* Is the 4758 Coprocessor finding a key store file? If you do not explicitly use the 
Key_Store_Designate SAPI, the CCA CSP support will attempt to use the files named on the device 
description. If you have named no files on the device description, the 4758 Coprocessor will not find any 
files. 

¢ Have you loaded and set a master key? The 4758 Coprocessor will not complete any cryptographic 
requests other than those for configuring your 4758 Coprocessor, unless you load a master key. 

* Does the Old master key register contain a key? The 4758 Coprocessor cannot re-encrypt keys 
under the Current master key unless the Old master key register contains a value. 

* Does your default role have authority to use a given hardware command? If not, you will need to 
log on by using a profile that uses a role that has the correct authority. 


* Does any role have authority to use a given hardware command? If your 4758 Coprocessor 
requires the hardware command and you have not authorized a role to use that command, you must 
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reinitialize your 4758 Coprocessor. Do this by using either the Cryptographic_Facility_Control API or the 
Hardware Service Manager that is found in System Service Tools. Using the 
Cryptographic_Facilty_Control API requires that you authorize a role to the hardware command that 
reinitializes the 4758 Coprocessor. If no such role exists, you must use the Hardware Service Manager. 


¢ Is a function control vector loaded? Your 4758 Coprocessor cannot run any cryptographic operations 
other than configuration until you load a function control vector. 


¢ Is one of the Cryptographic Access Provider products installed? IBM ships the function control 
vectors with these products. 


¢ If you are loading a master key, did you begin by clearing out the new master key register? If 
your 4758 Coprocessor has a partially loaded new master key register, you cannot load the first part of 
a master key. 


¢ Did you remember to set the clock in your 4758 before removing the authority to do so from the 
DEFAULT role? If not, you must reinitialize your 4758 Coprocessor by using either the 
Cryptographic_Facility_Control API or the Hardware Service Manager found in System Service Tools. 
Using the Cryptographic_Facilty_Control API requires that you authorize a role to the hardware 
command that reinitializes the 4758 Coprocessor. If no such role exists, you must use the Hardware 
Service Manager. 


* Did you set the EID before trying to generate public-private key pairs? You must set the EID 
before you can generate RSA keys. 


¢ Did you correctly initialize the first byte of a null key token to binary 0? If not, the CCA support 
may try to use it as a key label. CCA Support will either report it as a bad label format or report that it 
could find the key record. 


* Do you use the same name for a label in a PKA key store file and a retained PKA key? If so, your 
4758 Coprocessor will never find the retained key because the 4758 Coprocessor always searches the 
key store file first. 


* Do you have EBCDIC data in any fields in a skeleton PKA key token? The 4758 Coprocessor 
specifically checks for ASCII data in a number of the fields and will return an error if it finds EBCDIC 
data. 


For further troubleshooting information, see |‘Reinitialize the 4758 Cryptographic Coprocessor’| and 
the Hardware Service Manager” on page 274 


Reinitialize the 4758 Cryptographic Coprocessor 


If you set up your 4758 Coprocessor incorrectly, you can end up with an unusable configuration with which 
you cannot perform any cryptographic functions and cannot use any of the APIs to recover. For example, 
you can configure it such that you have no role authorized to set the master key and no role authorized to 
change or create new roles or profiles. 


You can call the hardware command for reinitializing the card by using the Cryptographic_Facility_Control 
(CSUACFC) SAPI. Two example programs are provided for your consideration. One of them is written in 
ILE C, while the other is written in ILE RPG. Both perform the same function. 


“Example: ILE C program for reinitializing the 4758 Coprocessor” on page 268 
“Example: ILE RPG program for reinitializing your 4758 Coprocessor’” on page 270 


Note: If you choose to use the program example that is provided, change it to suit your specific needs. 
For security reasons, IBM recommends that you individualize these program examples rather than 
using the default values provided. 


However, in some cases, there may not be a role that is authorized to any hardware command. In this 


case, you must reload the Licensed Internal Code by using the function that is provided in Hardware 
Service Manager in System Service Tools as described in|“Use the Hardware Service Manager’ on 
page 274] 274 
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Updating the Licensed Internal Code in the 4758 Coprocessor 


Loading the Licensed Internal Code in your 4758 Coprocessor erases the master key, all private keys, and 
all roles and profiles that are stored in your 4758 Coprocessor. Because of this, the server does not 
automatically load PTFs for the Licensed Internal Code in the 4758 Coprocessor, and the PTFs always 
require action on your part to enable them. Before you load the Licensed Internal Code, take appropriate 
actions to ensure that you can recover, such as ensuring that you have a hard copy of your master key. 


Note: If you randomly generated your master key, you will need to clone that key into a second 4758 
Coprocessor. If you do not, you will lose all your encrypted keys when you reinitialize your 4758 
Coprocessor. 


Example: ILE C program for reinitializing the 4758 Coprocessor 
Change this program example to suit your needs for reinitializing your 4758 Coprocessor. 


Note: Read the|Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


[essa cteee Sansa es oes see ses se soecsae saee=as sos See seasseeesecss-ee=ess= */ 
/* Clear the 4758 card (reset to manufactured state). */ 
/* x/ 
/* x/ 
/* COPYRIGHT 5769-SS1 (C) IBM CORP. 1999 */ 

/* x/ 
/* This material contains programming source code for your x/ 
/* consideration. These examples have not been thoroughly */ 
/* tested under all conditions. IBM, therefore, cannot */ 
/* guarantee or imply reliability, serviceability, or function */ 
/* of these program. All programs contained herein are x/ 
/* provided to you "AS IS". THE IMPLIED WARRANTIES OF x/ 
/* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE x/ 
/* ARE EXPRESSLY DISCLAIMED. IBM provides no program services for */ 
/* these programs and files. x/ 
/* x/ 
/* x/ 
/* Note: This verb is more fully described in Chapter 2 of x/ 
/* IBM 4758 CCA Basic Services Reference and Guide x/ 
/* (SC31-8609) publication. */ 
/* x/ 
/* Parameters: x/ 
/* none. */ 
/* x/ 
/* Example: */ 
/* CALL PGM(REINIT) */ 
/* x/ 
/* x/ 
/* Note: This program assumes the device to use is x/ 
/* already identified either by defaulting to the CRPO1 */ 
/* device or by being explicitly named using the */ 
/* Cryptographic Resource Allocate verb. Also this x/ 
/* device must be varied on and you must be authorized */ 
/* to use this device description. */ 
/* x/ 
/* Use these commands to compile this program on iSeries: */ 
/* ADDLIBLE LIB(QCCA) x/ 
/* CRTCMOD MODULE(REINIT) SRCFILE(SAMPLE) */ 
/* CRTPGM PGM(REINIT) MODULE(REINIT) BNDSRVPGM(QCCA/CSUACFC) x/ 
/* x/ 
/* Note: Authority to the CSUACFC service program in the x/ 
/* QCCA library is assumed. */ 
/* x/ 
/* The Common Cryptographic Architecture (CCA) verb used is */ 
/* Cryptographic_Facilitiess Control (CSUACFC). x/ 
/* x/ 
[eacese Stee s oe ee seaeeeeeest eseece dene eee ese seeeee et ese ces scuesese «/ 
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#include "csucincl.h" /* header file for CCA Cryptographic x/ 
/* Service Provider for iSeries x/ 
#include <stdio.h> 
#include <string.h> 
#include <stdlib.h> 
/¥eeseeeeese sense sees sesea seco eee se eSe see saces sees a seesesec ces sens */ 
/* standard return codes x/ 
esas seeSeeseese sss ose sasosso—— sae S— eee aa aa ese aa es seescores] «/ 
#define ERROR -1 
#define OK 0 
#define WARNING 4 
#define TOKENSIZE 8 /* number of bytes in random token */ 
int main(int argc, char *argv[]) 
{ 
| ee ee eee eee se ee eee eee eee eee «/ 
/* standard CCA parameters */ 
| Reese eee sees = ses a sea a sas see eS a ee sees oes «/ 
long return_code = 0; 
long reason_code = 0; 
long exit_data_length = 2; 
char exit_data[4]; 
char rule_array[2] [8]; 
long rule_array_count = 2; 
[Rate Seesesssesssatesouenssssstesscseseesesesssesssesses sesesesssssece «/ 
/* fields unique to this sample program */ 
[Reeve Soe sea seses eee ee tees eeseese ee eee beeaeeeteeesece see seaseesseee «/ 
long verb_data_length = TOKENSIZE; 
char verb_data[TOKENSIZE] ; 
char verb_data2[TOKENSIZE] ; 
int i; 
/* set keywords in the rule array x/ 
memcpy (rule_array, "ADAPTER1RQ-TOKEN", 16) ; 
/* get a random token from the card - returned in verb_data x*/ 


CSUACFC(  &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&averb_data_length, 
(char *)verb_data); 


if ( (return_code == OK) | (return_code == WARNING) ) 
printf("Random token was successfully returned. \n"); 
printf("Return/reason codes "); 


printf ("%ld/%ld\n\n", return_code, reason_code); 


/* get the one's complement of token and store in verb_data2. 
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/* operate on one byte at a time x/ 


for(i = 0; i < TOKENSIZE; i++) 
{ 


} 


/* change keyword in rule array */ 


verb_data2[i] = “verb _data[i]; 


memcpy (&rule_array[1],"RQ-REINT",8) ; 
/* invoke the verb to reset the card x*/ 


CSUACFC( &return_code, 
&reason_code, 
&exit_data_length, 
exit_data, 
&rule_array_count, 
(char *)rule_array, 
&averb_data_length, 
verb_data2) ; 


if ( (return_code == OK) | (return_code == WARNING) ) 
| printf("4758 card successfully cleared/reset.\n"); 
printf("Return/reason codes "); 
printf ("%ld/%ld\n\n", return_code, reason_code); 
return (OK); 


else 

{ 
printf("An error occurred while clearing the 4758 "); 
printf("card.\n Return/"); 
printf("reason codes %1d/%ld\n\n", return_code, reason_code) ; 


return(ERROR) ; 


} 


else 


{ 


printf("An error occurred while getting the random token. \n"); 


} 


printf("Return/reason codes "); 
printf ("%ld/%ld\n\n", return_code, reason_code); 


return (ERROR) ; 
} 


} 


Example: ILE RPG program for reinitializing your 4758 Coprocessor 
Change this program example to suit your needs for reinitializing your 4758 Coprocessor. 


Note: Read the/Chapter 7, “Code disclaimer information” on page 283) for important legal information. 


DA KRAKKKKK KKK ERK KK KEK KKK ERK KKK KEK KKK RRR KERR KEK KR ERR KERR RK REE RRR 
D* REINIT 

Dx 

D* Clear the 4758 card (reset to manufactured state). 

Dx« 
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Dx 


D* COPYRIGHT 5769-SS1 (C) IBM CORP. 2000, 2000 


Dx 


D* This material contains programming source code for your 


D* consideration. 


D* tested under all conditions. 


These example has not been thoroughly 
IBM, therefore, cannot 


D* guarantee or imply reliability, serviceability, or function 
All programs contained herein are 


D* of these programs. 


D* provided to you "AS IS". 


THE IMPLIED WARRANTIES OF 


D* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 


D* ARE EXPRESSLY DISCLAIMED. 


D* these programs and files. 


IBM provides no program services for 


Dx« 

Dx 

Dx Note: Input format is more fully described in Chapter 2 of 
Dx IBM 4758 CCA Basic Services Reference and Guide 

Dx (SC31-8609) publication. 

Dx 

D* Parameters: 

D« char * new time 16 characters 

Dx« 

D* Example: 


D* CALL PGM(REINIT) 
Dx 


D* Use these commands to compile this program on iSeries: 
D* CRTRPGMOD MODULE(REINIT) SRCFILE(SAMPLE) 
D* CRTPGM PGM(REINIT) MODULE(REINIT) 


Dx BNDSRVPGM(QCCA/CSUACFC) 

Dx 

D* Note: Authority to the CSUACFC service program in the 
Dx QCCA library is assumed. 

Dx« 


D* The Common Cryptographic Architecture (CCA) verbs used are 
D* Cryptographic_Facilty Control (CSUACFC) 


DA KRKK KARR KKK KKK KEKE KKK ERK KERR RRR KERR RRR RRR RRR RRR RRR KERR ER ERR 


Dx« 

Dx« ** 
DRETURNCODE Ss 
Dx ** 
DREASONCODE Ss 
Dx ** 
DEXTTDATALEN Ss 
Dx ** 
DEXITDATA S 
Dx« ** 
DRULEARRAYCNT Ss 
Dx« ** 
DRULEARRAY S 
Dx« ** 
DVERBDATALEN S 
Dx ** 
DVERBDATA Ss 
Dx 

DBUFFER DS 
DA1 

DA2 

DA3 

DA4 

Dx 

DWORKBUFF DS 
DINT4 


Return code 

9B 0 
Reason code 

9B 0 
Exit data length 

9B 0 
Exit data 

4 
Rule array count 

9B 0 
Rule array 

16 
Verb data length 

9B 0 
Verb data 


1 2 
3 4 
a) 6 
7 8 
1 4B 0 
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DINT2 3 4 
Dx« 

Dx 

DA KRKKKKKKKK KEKE KK KEK KKK ERK KERR KKK RRR RRR RRR RR ER KER RRR KERR ERR 
D* Prototype for Cryptographic_Facilty Control (CSUACFC) 


DA KRRK KKK KKK KEK KK KKK KKK ERK KKK KERR KEKE KEK KERR KKK KEE KKK ERK KERR KEK 


DCSUACFC PR 

DRETCODE 9B 0 

DRSNCODE 9B 0 

DEXTDTALEN 9B 0 

DEXTDTA 4 

DRARRAYCT 9B 0 

DRARRAY 16 

DVRBDTALEN 9B 0 

DVRBDTA 8 

Dx« 

DeoSSsaesc sles sense eseeasee aces see lees eset ee eee se sae cles ses se 
Dx ** Declares for sending messages to the 

Dx ** job log using the QMHSNDPM API 

Og eee ee ee ee 
DMSG S 75 DIM(3) CTDATA PERRCD(1) 
DMSGLENGTH S 9B 0 INZ(64) 

D DS 

DMSGTEXT 1 80 

DFAILRETC 41 44 

DFAILRSNC 46 49 

DMESSAGEID S 7 INZ(' ') 
DMESSAGEFILE S 21 INZ(' 

DMSGKEY S 4 INZ(' ') 

DMSGTYPE S 10 INZ('*INFO ') 
DSTACKENTRY S 10 INZ('* ') 
DSTACKCOUNTER S 9B 0 INZ(2) 

DERRCODE DS 

DBYTESIN 1 4B 0 INZ(0) 

DBYTESOUT 5 8B 0 INZ(0) 

Cx 

CR KKK KKK KKK KK EKER EKER KER EKER KKK EK KERR EK ERR ER ERR ER ERE RK RR ERREERE 
Cx START OF PROGRAM * 
Cx« * 
Cx * 
CkXSeSistSec pees ceece ses Sesee ee ese Se oe See ee eee tee Sci * 
Cx Set the keyword in the rule array * 
Ck wee sees eee eee eet ee ew ese eee eee ee eee eee senses ewes * 
C MOVEL "ADAPTER1' RULEARRAY 

C MOVE "RQ-TOKEN' RULEARRAY 

¢ Z-ADD 2 RULEARRAYCNT 
CxkxSeeescsecSscescecesscssesecsseseSssSssassecsseosscessssceeess * 
Cx Set the verb data length to 8 * 
Cxkseecececeeeeceeece sees eee ees ese se sooo cece sce * 
C Z-ADD 8 VERBDATALEN 


CRRA KKK KKK KK KEKE KK EKER KER ER EKER KEKE KKK ERR ER ERR RR ERE RRR ERR ERE 


Cx Call Cryptographic Facilty Control SAPI 


CK KKK KKK KKK KK KEKE KR KK ERK KK ERE KKK KEK KEK KEK KERR ERE RK RR EKER ERR ERR ERE 


C CALLP CSUACFC (RETURNCODE: 
C REASONCODE: 
C EXITDATALEN: 
C EXITDATA: 
Cc RULEARRAYCNT : 
C RULEARRAY : 
C VERBDATALEN: 
C VERBDATA) 
(ee * 
Cx Check the return code * 
Ck eceeeeeeeessesennnesses * 
C RETURNCODE IFGT 4 
Cx« fessese Sees cecsocesese * 
Cx * Send error message * 
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*/ 


Cx« {icc ccceeeee sees e SSeS * 

C MOVEL MSG (1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

C RETURN 

C ENDIF 

Cx« 

Cx« tose sec eaceesseeeosassecsees ose sss keee * 

Cx * Send success message for the Ist step * 

Cx* acc son seca eseeoSeeseececewecweloace=ce= * 

C MOVEL MSG (2) MSGTEXT 

C EXSR SNDMSG 

Cx* 

CkxaSseSs sesso Sasa aeSS eS o Ses Seses seo ee sseo as sa-aSassaesse- seo Se * 
Cx Set the keyword in the rule array for 2nd step * 
CxkeSeSeecteceacsteeeeSecee cece es ee eee eee eee ce ls e ee eases * 
C MOVE "RQ-REINT' RULEARRAY 

Cx« 

CkeSsessesSsesa sa ossos So SeSse ses ees aaa asa a aa ae Sa ee ase Se Se ose * 
Cx Convert the token into the one's complement of it * 
Oe a eee * 
C MOVE VERBDATA BUFFER 

C Z-ADD 0 INT4 

C MOVE Al INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 Al 

C MOVE A2 INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 A2 

C MOVE A3 INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 A3 

C MOVE A4 INT2 

C EVAL INT4 = 65535 - INT4 

C MOVE INT2 A4 

C MOVE BUFFER VERBDATA 

Cx« 

CR KKK KKK KKK KK KKK KR KEKE KK KEK ERK KK EKER KKK RK KKK ER ERK RR ER ERE RK ERR ERE 
Cx Call Cryptographic Facilty Control SAPI */ 
CR KKK KK KKK KKK KEKE KR ERE RK ER ER KERR EKER KERR ERR ER ER ERR RR ERE RK RK ERR RR 
C CALLP CSUACFC (RETURNCODE: 

C REASONCODE: 

C EXITDATALEN: 

C EXITDATA: 

C RULEARRAYCNT : 

C RULEARRAY : 

C VERBDATALEN: 

C VERBDATA) 
Oe ee eee * 

Cx Check the return code * 

Cxesecscosstessesecscceses * 

C RETURNCODE IFGT 4 

Cx* a tec ce se ae i * 

Cx * Send error message * 

Cx* {tcccciaaceecesceoesacees * 

C MOVEL MSG(1) MSGTEXT 

C MOVE RETURNCODE FAILRETC 

C MOVE REASONCODE FAILRSNC 

C EXSR SNDMSG 

Cx« 

C ELSE 

Cx* Se a se ems mh meh * 

Cx * Send success message * 

Cx* {eccccencene aaa eS * 

C MOVE MSG (3) MSGTEXT 

C EXSR SNDMSG 
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Cx« 


C ENDIF 
C SETON LR 
Cx* 


CK K KKK KKK KKK KK KKK KR KK ERK KK ERE KK EKER KEK RRR KERR ERE RE R EKER KERR ERR ERE 


Cx Subroutine to send a message 
CK KK KK KEKE KKK KEK KER EKER KER ERE RRR KER KERR EKER ER ERK RR ERE RE RR ERE 


C SNDMSG BEGSR 

C CALL "QMHSNDPM' 

C PARM MESSAGEID 

C PARM MESSAGEFILE 
C PARM MSGTEXT 

C PARM MSGLENGTH 

C PARM MSGTYPE 

C PARM STACKENTRY 
C PARM STACKCOUNTER 
C PARM MSGKEY 

C PARM ERRCODE 

C ENDSR 


** 

CSUACFC failed with return/reason codes 9999/9999. 
Random token was successfully returned. 

The Cryptographic Coprocessor successfully cleared/reset. 


Use the Hardware Service Manager 


Hardware service manager is a tool for displaying and working with system hardware from both a logical 
and a packaging viewpoint, an aid for debugging Input/Output (I/O) processors and devices, and is also 
used to reinitialize the 4758 Coprocessor (set it back to an uninitialized state). 


When the 4758 Coprocessor is re-initialized, the 4758 Coprocessor Licensed Internal Code is reloaded 
into the Coprocessor. Some but not all program temporary fixes (PTFs) for the Coprocessor licensed 
internal code may require the use of hardware service manager to activate them. This extra step is 
included to allow you to prepare for recovery because reloading certain segments of the licensed internal 
code will cause any configuration data including master keys, retained RSA private keys, roles, and 
profiles to be lost. 


There may be situations where the 4758 Coprocessor must be reset back to an unintialized state. For 
example, if the Coprocessor is not configured correctly, there could be a scenario where the Coprocessor 
can not perform any useful function and cannot be corrected using the 4758 Coprocessor configuration 
utility or a user-written application. Another example is if the passwords for the administrative profiles are 
forgotten and no other profile uses a role that is authorized to change passwords. 


Hardware service manager is found in System Service Tools. Use the Start System Service Tools 


(STRSST) CL command by typing STRSST at the CL command line and pressing enter. The System 
Service Tools Signon display should be shown. 
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Start Service Tools (STRSST) Sign On 


SYSTEM: RCHSYSQ1 
Type choice, press Enter. 


Service tools user..... 
Service tools password... 


F3=Exit F9=Change Password F12=Cancel e: 


Enter the service tools user profile name and password. The System Service Tools display should appear. 


System Service Tools (SST) 


Select one of the following: 


Start a service tool 

Work with active service tools 
Work with disk units 

Work with diskette data recovery 
Work with system partitions 

Work with system capacity 


Doarwnrnr 


Selection 
i} 


F3=Exit F10=Command entry F12=Cancel y 


Select 1 to start a service tool and press Enter. The Start a Service Tool display will be shown. 


Start a Service Tool 


Warning: Incorrect use of this service tool can cause damage 
to data in this system. Contact your service representative 
for assistance. 


Select one of the following: 


Product activity log 

Trace Licensed Internal Code 
Work with communications trace 
Display/Alter/Dump 

Licensed Internal Code log 
Main storage dump manager 
Hardware service manager 


NOOB WNMNE 


Selection 
L. 


F3=Exit F12=Cancel F16=SST menu ry, 
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Select 7 to start Hardware Service Manager. The Hardware Service Manager screen will be displayed 
showing the menu of available options. 


a 


Hardware Service Manager 
Attention: This utility is provided for service representative use only. 


System unit. ..... . : 9406-270 10-4314M 
Release. ........ ? V5RIMO (1) 


Select one of the following: 


1. Packaging hardware resources (systems, frames, cards,...) 
2. Logical hardware resources (buses, I0Ps, controllers,...) 
3. Locate resource by resource name 
4. Failed and non-reporting hardware resources 
5. System power control network (SPCN) 
6. Work with service action log 
7. Display label location work sheet 
8. Device Concurrent Maintenance 
Selection 
zZ 
F3=Exit F6=Print configuration F9=Display card gap information 
F10=Display resources requiring attention F12=Cancel 


Select 2 to work with logical hardware resources. 


7 


Logical Hardware Resources 
Select one of the following: 


. System bus resources 

. Processor resources 

. Main storage resources 

. High-speed link resources 


BPwWNr 


Selection 
il 


ee F6=Print configuration F12=Cancel 


From the Logical Hardware Resources screen, select 1 to show system bus resources. 
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Logical Hardware Resources on System Bus 


System bus(es) to work with. ..... *ALL *ALL, *SPD, *PCI, 1-511 
SUBSE GD Y teres: wenmcatenecy teuce geeks smiray ssi raLeras *CRP *ALL, «STG, *WS, *CMN, *CRP 


Type options, press Enter. 
2=Change detail 4=Remove 5=Display detail 6=1/0 Debug 


8=Associated packaging resource(s) 9=Resources associated with IOP 
Resource 
Opt Description Type-Model Status Name 
_ HSL 1/0 Bridge 2249- Operational BCO2 
_ Bus Expansion Adapter - Operational BCCO2 
System Bus 2249- Operational LBO1 
Multi-Adapter Bridge 2249- Operational PCIO1D 
ix Combined Function IOP * < 284D-001 Operational CMBO1 
_ HSL 1/0 Bridge 283B- Operational BCO1 
Bus Expansion Adapter - Operational BCC03 
More... 


F3=Exit F5=Refresh  F6=Print F8=Include non-reporting resources 
F9=Failed resources F10=Non-reporting resources 
Fll=Display serial/part numbers F12=Cancel 


If you know which IOP contains the 4758, type 9 next to the IOP. Otherwise, subset the list by typing 
*CRP for "Subset by” field and then type 9 next to the IOP containing the 4758. You should then see the 
Logical Hardware Resources Associated with IOP display. 


Logical Hardware Resources Associated with IOP > 
Type options, press enter. 
2=Change detail 4=Remove 5=Display detail 6=1/0 Debug 
7=Verify 8=Associated packaging resource(s) 
Resource 
Opt Description Type-Model Status Name 
Combined function IOP * < 284D-001 Operational CMBO1 
_ Cryptography Adapter 4758-023 Operational CRPCTLO1 
6 Cryptography Device 4758-023 Operational CRPO1 
~ Workstation I0A 2746-001 Operational CTLO1 
Display Station 3477-OFC Operational DSP001 
Display Station 3477-OFC Operational DSP002 
Communications IOA 2745-001 Operational LINO1 
Communications Port 2745-001 Operational CMNO1 
is Communications Port 2745-001 Operational CMNO2 
Communications I0A 2744-001 Operational LINO3 
Communications Port 2744-001 Operational CMNO3 
More... 
F3=Exit F5=Refresh Fo=Print F8=Include non-reporting resources 
F9=Failed resources F10=Non-reporting resources 
Fll=Display serial/part numbers F12=Cancel 


Type 6 next to the cryptography device that you want to reinitialize, and then press Enter. 
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(— ~ 
Select Cryptography Debug Function 


Select one of the following: 


1. Reinitialize Flash Memory 
2. Select IOP Debug Function 


Selection 
1 


F3=Exit F12=Cancel 
NG pY 


Select 1 to reinitialize flash memory (reload the 4758 Coprocessor Licensed Internal Code). A confirmation 
screen will be displayed. If you are applying a PTF ensure that you have taken the necessary precautions 
regarding your encrypted data and keys, and have a backup of the master key. Press Enter to continue. 


ae 
Reinitialize Flash Memory Function 
DANGER: 
Performing this initialization of the flash memory on the cryptography 
device will cause ALL key information stored on the device to be 
DESTROYED. This will cause all data encrypted using this device to be 
rendered unusable. 
WARNING: 
Performing this initialization of the flash memory on the cryptography 
device will take an estimated 10 minutes. 
Press Enter to proceed. 
F3=Exit F12=Cancel 
XN ay 


The following screen showing status of the reinitialization will be displayed and updated until reinitialization 
is complete. 
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Reinitialize Flash Memory Status 


Flash memory reinitialization in progress... 


Estimated time: 10.0 minutes 


Elapsed time: 2.5 minutes 


When reinitialization is complete, a message will be displayed. 


Select Cryptography Debug Function 
Select one of the following: 


1. Reinitialize Flash Memory 
2. Select IOP Debug Function 


Selection 


F3=Exit F12=Cancel 
Reinitialization of cryptography device was successful. 


4 


After reinitialization is complete, exit all the way out of system service tools by pressing function key F3 on 
each screen as necessary. 
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Chapter 6. Related information for cryptographic hardware 


a 


The following resources provide additional information relating to cryptographic concepts or hardware: 


IBM Redbooks™ 


¢ IBM @server iSeries Wired Network Security: OS/400 V5R1 DCM and Cryptographic Enhancements 


IBM Sources 


¢ The|IBM Cryptographic hardware site contains information on the 4758 Cryptographic Coprocessor 


hardware solution for iSeries servers. 


¢« The|CCA Basic Services Manual is intended for systems and applications analysts and application 


programmers who will evaluate or create programs for the IBM 4758 Common Cryptographic 
Architecture (CCA) support. 


¢ The|IBM PCI Cryptographic Coprocessor documentation library’ 2 contains downloadable PDF 


documents that include general, support, and programming information for the 4758 Cryptographic 
Coprocessor. 


¢ The IBM|developerWorks ® site includes tutorials for cryptographic concepts, cryptography, and 
encryption. 


= 
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Chapter 7. Code disclaimer information 


This document contains programming examples. 


IBM grants you a nonexclusive copyright license to use all programming code examples from which you 
can generate similar function tailored to your own specific needs. 


All sample code is provided by IBM for illustrative purposes only. These examples have not been 
thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, 
or function of these programs. 


All programs contained herein are provided to you "AS IS” without any warranties of any kind. The implied 


warranties of non-infringement, merchantability and fitness for a particular purpose are expressly 
disclaimed. 
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